Skip to main content
Glama

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

Related MCP server: matter-mcp-server

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.

Available Tools

7 tools
lan_device_controlC

Send a command to a device.

Inputs: command (required), device_id (required), args. Returns: object

lan_device_listC

List registered devices with current status.

Inputs: filter_room, filter_type, online_only, filter_transport. Returns: object

lan_device_registerC

Promote a pending device to the registry.

Inputs: name (required), pending_id (required), room, adapter_type. Returns: object

lan_device_statusC

Get detailed current status of a device.

Inputs: device_id (required). Returns: object

lan_discoverA

Discover devices on local network and Bluetooth.

Scans WiFi/LAN and Bluetooth LE simultaneously. Returns a discovery report with new, updated, lost devices.

Inputs: scan_type, network_range, timeout_seconds. Returns: object

lan_discover_pendingB

List devices awaiting manual registration.

Inputs: filter_transport. Returns: object

lan_pending_dismissC

Dismiss a pending device (hide from pending list).

Inputs: pending_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: discovery trigger, pending list, pending registration, pending dismissal, registered device list, device control, and device status. No two tools overlap in purpose, so an agent can easily select the correct tool for a given task.

    Naming Consistency4/5

    All tools share the 'lan_' prefix, providing a unified namespace. However, naming mixes verb-first (lan_discover) and noun-first (lan_device_register) patterns, and lan_device_status uses a noun instead of an action verb. These are minor deviations that don't severely impair readability.

    Tool Count5/5

    Seven tools is ideal for a local network device management server. The set covers discovery, the pending device workflow, and registered device operations without unnecessary redundancy, fitting comfortably within the 3-15 tool range.

    Completeness4/5

    The tool set covers the core lifecycle from discovery through pending approval and registration, plus device listing, control, and status retrieval. Notable gaps include no unregister/delete operation for registered devices and no update device details, but these are minor for a LAN management use case.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers