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.