iotforge

An MCP server for discovering and controlling IoT devices on your local network and via Bluetooth LE.

What it does

iotforge exposes your LAN and BLE devices as MCP tools so any MCP-compatible AI assistant can:

• Discover devices on your local network (mDNS, ARP) and Bluetooth LE
• Register discovered devices into a persistent inventory
• Control devices through adapter plugins (smart plugs, BLE lights, etc.)
• Query device status and inventory via MCP resources

Architecture

MCP Client (Claude, etc.)
    │
    ▼
┌─────────────────────────────┐
│  iotforge MCP Server        │
│  (stdio or SSE transport)   │
├─────────────────────────────┤
│  Tools: discover, register, │
│         control, status     │
│  Resources: inventory,      │
│             pending         │
├─────────────────────────────┤
│  Core: Scanner, Registry,   │
│        Discovery Service    │
├─────────────────────────────┤
│  Adapters: Meross, BLE      │
│  Database: SQLite (async)   │
└─────────────────────────────┘
    │               │
    ▼               ▼
  LAN/mDNS       BLE/GATT

MCP Tools

| Tool | Description | |------|-------------| | lan_discover | Scan WiFi/LAN and BLE for devices | | lan_discover_pending | List devices awaiting registration | | lan_device_register | Promote a pending device to the registry | | lan_pending_dismiss | Dismiss a pending device | | lan_device_list | List registered devices with filters | | lan_device_control | Send a command to a device | | lan_device_status | Get current device status |

MCP Resources

| Resource | Description | |----------|-------------| | devices://inventory | Full device inventory (markdown) | | devices://pending | Pending devices (markdown) |

Installation

pip install -e ".[all]"

Optional extras: meross (Meross smart plugs), ble (Bluetooth LE via bleak).

Configuration

Copy config.example.yaml and edit:

cp config.example.yaml config.yaml

Key settings: network range, scan intervals, transport mode (stdio/SSE), database path.

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "iotforge": {
      "command": "iotforge",
      "args": ["config.yaml"]
    }
  }
}

Standalone (SSE mode)

iotforge config.yaml

Set server.transport: sse in your config to expose an HTTP endpoint.

BLE Scripts

The scripts/ directory contains standalone BLE utilities:

• elk_ble_ctl.py — GATT controller for ELK-BLEDDM LED strips (service 0xFFF0)
• lampsmart_pro.py — BLE ADV broadcast controller for LampSmart Pro ceiling lights (multiple protocol versions)
• ble_adv_sniffer.py — Raw HCI BLE advertisement sniffer for protocol discovery

Adapters

iotforge uses a plugin adapter system. Built-in adapters:

• meross — Meross smart plugs/switches (requires meross-iot)
• ble_light — BLE GATT light control (requires bleak)

Custom adapters implement the BaseAdapter interface in src/iotforge/adapters/base.py.

Development

pip install -e ".[dev]"
ruff check .
python -m pytest --cov=iotforge

License

MIT — see LICENSE.