Local Home Devices MCP

MCP (Model Context Protocol) server for IoT device management. Enables AI assistants (Claude Desktop, LibreChat, Cline) to discover and control OpenBK (OpenBeken), Tasmota, and Tuya devices on your local network.

Architecture

Verify

# Health check
curl http://localhost:9100/health

# List all MCP tools
curl http://localhost:9102/api/tools

# Call a tool via REST API
curl -X POST http://localhost:9102/api/tools/iot_list_devices \
  -H "Content-Type: application/json" \
  -d '{}'

Available Tools

Device Discovery

All read-only operations - no device state is modified.

Device Information

All read-only operations - no device state is modified.

Device Control

Device Configuration

Introspection

MQTT Integration

OpenHASP Panels

Hikvision Doorbell

Note: Tools marked [CONTAINER] require the hikvision-doorbell Docker container and access to /var/run/docker.sock. ISAPI-only tools work with any Hikvision doorbell accessible via HTTP Digest Auth.

Project Structure

• tools/constants.py - All shared configuration defaults (no hardcoded IPs in tool files)
• tools/validators.py - Input validation for tool parameters
• tools/iot_control.py - Power/brightness/restart/WiFi control (4 tools)
• tools/iot_devices.py - Device info/power state (2 tools)
• tools/iot_discovery.py - Network scanning/device discovery/cache (4 tools)
• tools/iot_mqtt.py - MQTT publish/state/topic (3 tools)
• tools/iot_meta.py - Capability introspection, manifests and transports (1 tool)
• tools/iot_tuya.py - Tuya device cloud + local control + diagnostics (10 tools)
• tools/iot_openhasp.py - OpenHASP panel control, diagnostics, Telnet (20 tools)
• tools/openhasp/ - OpenHASP HTTP, Telnet, diagnostics helpers
• tools/iot_config.py - Device configuration tools (7 tools)
• tools/iot_hikvision.py - Hikvision doorbell tools (14 tools)
• tools/hikvision/ - ISAPI HTTP client, Docker socket helper
• tools/http_session.py - Generic IoT device HTTP client module

Supported Devices

OpenBK (OpenBeken)

• Chips: BK7231N, BK7231T, XR809, BL602
• Devices: Lights, switches, curtains, sensors
• Detection: HTTP GET /index returns HTML containing "openbeken"

Tasmota

• Chips: ESP8266, ESP32
• Devices: Lights, switches, sensors, fans, plugs
• Detection: HTTP GET /cm?cmnd=Status returns JSON with "Status" key

Tuya

• Chips: ESP8266, ESP32, BK7231N/T (varies by vendor)
• Devices: Vacuums, kettles, water valves, sensors, gateways
• Detection: TCP port 6668 open on local network
• Requirements: Tuya cloud API credentials (Access ID, Access Secret) for local key retrieval
• Protocol: Encrypted TCP/UDP via tinytuya library, cloud API fallback

OpenHASP

• Chips: ESP32 (WT32-SC01, WT32-SC01 Plus, ESP32-S3)
• Devices: Touch panel displays, wall-mounted dashboards, control panels
• Detection: HTTP GET /config.json returns JSON with "hasp" key
• Protocol: HTTP API for config/files + raw TCP Telnet for control (NOT telnetlib)
• Telnet: Uses raw TCP socket - MQTT PUB format when MQTT connected, MSGR format otherwise

Hikvision Doorbell

• Models: DS-KV6113-WPE1(C), DS-KV8113-WPE1(C), VillaVTO series
• Features: Camera snapshot, motion detection (VMD), gate control, event triggers, ISAPI health
• Detection: Docker container hikvision-doorbell manages ISAPI connection
• Protocol: ISAPI HTTP Digest Auth + Docker Unix socket API
• Requirements: Docker container hikvision-doorbell, ISAPI credentials (HIKVISION_DOORBELL_HOST/USER/PASSWORD)

Testing

The project has a 4-tier test hierarchy (see AGENTS.md for details):

Unit tests run in CI. Integration, smoke, and e2e tests skip when their dependencies (MQTT broker, running server) are absent.

The server follows the MCP Server Standards at L2/L3 maturity level.

Requirements

• Docker (recommended) or Python 3.11+ (for local use)
• MQTT broker (optional - required only for MQTT tools)
• OpenBK or Tasmota devices on the same local network
• Tuya devices (WiFi models; optional - requires Tuya cloud API credentials)
• nmap - installed automatically in Docker; for local use, install via apt-get install nmap (may require root/sudo)

Note on networking: Docker uses --network host mode to access the local network where your IoT devices are located. This is required for nmap scanning and direct HTTP communication with devices.

Quick Start

1. Configure

cp .env.example .env
# Edit .env with your MQTT_BROKER and network range

2. Run with Docker

Option A -- Pre-built image from GitHub Container Registry:

docker run -d \
  --name local-home-devices-mcp \
  --network host \
  -e MQTT_BROKER=192.168.1.100 \
  -e START_IP=192.168.1.1 \
  -e END_IP=192.168.1.254 \
  -v local-home-devices-data:/app/data \
  ghcr.io/paulomac1000/local-home-devices-mcp:latest

Option B -- with docker compose:

cp .env.example .env
# edit .env with your settings
docker compose up -d

Option C -- Build locally:

docker build -t local-home-devices-mcp .
docker run -d \
  --network host \
  -e MQTT_BROKER=192.168.1.100 \
  -e START_IP=192.168.1.1 \
  -e END_IP=192.168.1.254 \
  -v local-home-devices-data:/app/data \
  local-home-devices-mcp

3. Run locally (Python 3.11+)

pip install -r requirements.txt
MQTT_BROKER=192.168.1.100 START_IP=192.168.1.1 END_IP=192.168.1.254 python server.py

Configuration

All configuration is via environment variables. See .env.example for a complete template.

Required for MQTT tools (optional otherwise)

Tip: Without MQTT broker, device discovery and HTTP control still work. Set MQTT_BROKER only if you need MQTT-based tools (iot_mqtt_publish, iot_mqtt_get_state, etc.).

Network Scanning

Optional

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "local-home-devices": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9101/sse"]
    }
  }
}

License

MIT -- see LICENSE for details.