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. - 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. ``` `cp .env.example .env # Edit .env with your MQTT_BROKER and network range` ``` **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` ``` ``` `cp .env.example .env # edit .env with your settings docker compose up -d` ``` ``` `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` ``` ``` `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` ``` ``` `# 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 '{}'` ``` All read-only operations - no device state is modified. All read-only operations - no device state is modified. **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. 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.). - `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 - **Chips**: BK7231N, BK7231T, XR809, BL602 - **Devices**: Lights, switches, curtains, sensors - **Detection**: HTTP`GET /index`returns HTML containing`"openbeken"` - **Chips**: ESP8266, ESP32 - **Devices**: Lights, switches, sensors, fans, plugs - **Detection**: HTTP`GET /cm?cmnd=Status`returns JSON with`"Status"`key - **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 - **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 - **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`) 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 Standardsat L2/L3 maturity level. Add to your`claude_desktop_config.json`: ``` `{ "mcpServers": { "local-home-devices": { "command": "npx", "args": ](https://github.com/paulomac1000/ai-skills/blob/main/skills/mcp-server-architect/mcp-server-standards.md)["-y", "mcp-remote", "http://localhost:9101/sse"] } } }` ``` Control AVM FRITZ!Box routers - manage devices, WiFi, network settings, parental controls, and schedule time-delayed actions A free, private, and secure remote MCP server for Home Assistant. MCP server for Google Cast — discover devices, play media, control volume, launch apps, and manage queues over stdio A safe-by-default MCP server that exposes your Control4 home automation (lights, scenes, locks, thermostats, and media) as structured tools over HTTP and Claude Desktop STDIO for reliable AI-powered control on your local network. Control and query the status of Ecovacs cleaning robots using the MCP protocol. Allows an LLM agent to control your Gaggimate espresso machine An MCP server for the Gaggiuino open-source espresso machine, providing real-time local network access to machine status and shot data. A Model Context Protocol (MCP) server that provides AI assistants with access to Home Assistant, enabling smart home control and automation management. Read-only MCP (Model Context Protocol) server for Home Assistant. Gives AI assistants (Claude Desktop, LibreChat, Cline) full observability into your smart home — entity states, automations, scripts, devices, logs, diagnostics — without any write access. Also generates static AI context snapshots for RAG systems, ChatGPT Projects, Qwen, and other tools that accept custom knowledge files. Built in Python, runs anywhere — locally, in Docker, or as an MCP integration. Native macOS HomeKit integration for AI assistants via Model Context Protocol