[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-79889":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":24,"discoverSource":25},79889,"homeassistant-mcp","robbrad\u002Fhomeassistant-mcp","robbrad","Home Assistant MCP Server - Control your smart home with AI assistants via the Model Context Protocol",null,"Python",99,5,2,0,2.33,"MIT License",false,"main",true,[],"2026-06-12 02:03:55","# Home Assistant MCP Server\n\nA Model Context Protocol (MCP) server that lets AI assistants control Home Assistant. Built with Python and [FastMCP](https:\u002F\u002Fgithub.com\u002Fjlowin\u002Ffastmcp).\n\nWorks with Claude, GPT-4, Cursor, Kiro, and any MCP-compatible client.\n\n## What it does\n\n- **40 tools** covering lights, climate, covers, locks, media players, vacuums, fans, cameras, alarms, and more\n- **BM25 tool search** — LLMs discover tools on demand instead of receiving all 40 schemas upfront\n- **MCP Resources** for read-only entity, area, device, and service data\n- **MCP Prompts** for guided workflows (automation creation, troubleshooting, energy optimization)\n- **Tool annotations** — `readOnlyHint` lets clients skip confirmation prompts for safe operations\n- **Smart error log parsing** — deduplicates and summarises HA error logs instead of dumping raw text\n- **Context-aware responses** — compact list responses, domain-filtered queries, progress reporting\n- **Async throughout** with TTL-based caching to reduce API load\n\n## Installation\n\n### uvx (recommended)\n\nNo install needed. Just configure your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"homeassistant\": {\n      \"command\": \"uvx\",\n      \"args\": [\"homeassistant-mcp\"],\n      \"env\": {\n        \"HASS_HOST\": \"http:\u002F\u002Fhomeassistant.local:8123\",\n        \"HASS_TOKEN\": \"your_long_lived_access_token_here\"\n      }\n    }\n  }\n}\n```\n\n### pip\n\n```bash\npip install homeassistant-mcp\nhomeassistant-mcp\n```\n\n### From source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Frobbrad\u002Fhomeassistant-mcp.git\ncd homeassistant-mcp\npython -m venv venv\nsource venv\u002Fbin\u002Factivate  # Windows: venv\\Scripts\\activate\npip install -e \".[dev]\"\nhomeassistant-mcp\n```\n\n## Configuration\n\nThe server needs two environment variables:\n\n| Variable | Description |\n|----------|-------------|\n| `HASS_HOST` | Home Assistant URL, e.g. `http:\u002F\u002Fhomeassistant.local:8123` |\n| `HASS_TOKEN` | Long-lived access token ([how to create one](https:\u002F\u002Fwww.home-assistant.io\u002Fdocs\u002Fauthentication\u002F#your-account-profile)) |\n\nOptional:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CACHE_TTL_STATES` | `30` | Cache TTL for bulk state queries (seconds) |\n| `CACHE_TTL_ENTITY` | `10` | Cache TTL for individual entity queries (seconds) |\n| `LOG_LEVEL` | `INFO` | Logging level |\n\nThese can be set via environment variables (as shown in the MCP client configs above) or in a `.env` file. See [.env.example](.env.example).\n\n## MCP Client Setup\n\n### Claude Desktop\n\nAdd to your config file:\n- macOS: `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"homeassistant\": {\n      \"command\": \"uvx\",\n      \"args\": [\"homeassistant-mcp\"],\n      \"env\": {\n        \"HASS_HOST\": \"http:\u002F\u002Fhomeassistant.local:8123\",\n        \"HASS_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\n### Cursor \u002F Kiro \u002F Other MCP Clients\n\nSame config format. Place it in your client's MCP configuration file (e.g. `.cursor\u002Fmcp.json`, `.kiro\u002Fsettings\u002Fmcp.json`).\n\nThe server uses stdio transport, which is the standard for MCP.\n\n## How Tool Discovery Works\n\nWith 40 tools, the server uses BM25 search to keep the LLM's context lean. Instead of sending all 40 tool schemas upfront, the LLM sees 8 tools:\n\n| Tool | Purpose |\n|------|---------|\n| `discover_tools` | Returns the full catalog of all 40 tools by category |\n| `states_control` | Entity state management (list, get, set, delete) |\n| `list_devices` | Device discovery with domain\u002Farea\u002Ffloor filtering |\n| `call_service` | Call any HA service directly |\n| `template_render` | Render Jinja2 templates in HA context |\n| `error_log_get` | Parsed and deduplicated error log summary |\n| `search_tools` | BM25 search to find tools by description |\n| `call_tool` | Execute a discovered tool by name |\n\nThe LLM calls `discover_tools()` to see what's available, then `search_tools(query=\"lights brightness\")` to get the full schema, then calls the tool directly.\n\n## All Tools\n\n### Device Control (16 tools)\n\n| Tool | Domain | Capabilities |\n|------|--------|-------------|\n| `lights_control` | light | Brightness, color temp, RGB |\n| `climate_control` | climate | HVAC modes, temperature, fan |\n| `switch_control` | switch | On\u002Foff, bulk operations |\n| `cover_control` | cover | Position, tilt, open\u002Fclose |\n| `lock_control` | lock | Lock\u002Funlock with codes |\n| `media_player_control` | media_player | Playback, volume, source |\n| `camera_control` | camera | Snapshots, streams, motion detection |\n| `vacuum_control` | vacuum | Start, dock, fan speed |\n| `fan_control` | fan | Speed, oscillation, direction |\n| `alarm_control` | alarm_control_panel | Arm\u002Fdisarm modes |\n| `weather_control` | weather | Conditions, daily\u002Fhourly forecasts |\n| `water_heater_control` | water_heater | Temperature, modes |\n| `humidifier_control` | humidifier | Humidity levels |\n| `siren_control` | siren | Activation control |\n| `valve_control` | valve | Open\u002Fclose |\n| `lawn_mower_control` | lawn_mower | Start, stop, dock |\n\n### Automation & Scenes (3 tools)\n\n| Tool | Capabilities |\n|------|-------------|\n| `automation_control` | List, trigger, enable, disable, reload |\n| `scene_control` | List, activate |\n| `script_control` | List, execute with variables, reload |\n\n### Input Helpers (5 tools)\n\n| Tool | Capabilities |\n|------|-------------|\n| `input_boolean_control` | Toggle on\u002Foff |\n| `input_number_control` | Set value, increment, decrement |\n| `input_select_control` | Select from options |\n| `input_text_control` | Set text value |\n| `input_datetime_control` | Set date\u002Ftime |\n\n### API & State (4 tools)\n\n| Tool | Capabilities |\n|------|-------------|\n| `api_info` | API status, HA config, loaded components |\n| `events_control` | List event types, fire custom events |\n| `services_control` | List services by domain, call services |\n| `states_control` | List\u002Fget\u002Fset\u002Fdelete entity states with filtering |\n\n### History (3 tools)\n\n| Tool | Capabilities |\n|------|-------------|\n| `history_query` | State changes by entity + hours (not ISO timestamps) |\n| `logbook_query` | Human-readable logbook entries |\n| `error_log_get` | Parsed, deduplicated error summary with component counts |\n\n### Specialized (5 tools)\n\n| Tool | Capabilities |\n|------|-------------|\n| `calendar_access` | List calendars, get events by date range |\n| `camera_proxy_get` | Camera images with optional resize |\n| `config_check` | Validate HA configuration |\n| `intent_handle` | Process natural language intents |\n| `template_render` | Render Jinja2 templates |\n\n### General (4 tools)\n\n| Tool | Capabilities |\n|------|-------------|\n| `list_devices` | Filter by any domain, area, or floor |\n| `call_service` | Call any HA service with custom data |\n| `send_notification` | Send alerts via HA notification services |\n| `discover_tools` | Full tool catalog for LLM discovery |\n\n## MCP Resources\n\n| URI Pattern | Description |\n|-------------|-------------|\n| `hass:\u002F\u002Fentity\u002F{entity_id}` | Entity state and attributes |\n| `hass:\u002F\u002Farea\u002F{area_id}` | Area entities (compact summaries) |\n| `hass:\u002F\u002Fdevice\u002F{device_id}` | Device entities (compact summaries) |\n| `hass:\u002F\u002Fservices` | All services organized by domain |\n| `hass:\u002F\u002Fentity\u002F{entity_id}\u002Fhistory` | Entity history with pagination |\n\n## Development\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Frobbrad\u002Fhomeassistant-mcp.git\ncd homeassistant-mcp\npython -m venv venv\nsource venv\u002Fbin\u002Factivate\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format and lint\nblack src\u002F tests\u002F\nruff check src\u002F tests\u002F\n\n# Type check\nmypy src\u002F\n```\n\n### Publishing\n\nCommits to `main` auto-publish to PyPI via GitHub Actions + python-semantic-release:\n- `fix:` commits → patch bump (3.1.0 → 3.1.1)\n- `feat:` commits → minor bump (3.1.0 → 3.2.0)\n- `BREAKING CHANGE:` → major bump (3.1.0 → 4.0.0)\n\n## Architecture\n\n```\nAI Assistant  \u003C-->  MCP Server (FastMCP\u002Fstdio)  \u003C-->  Home Assistant REST API\n                         |\n                   +-----+-----+\n                   |           |\n                 Tools      Cache\n                 Layer      Layer\n```\n\n- **FastMCP Server** handles MCP protocol over stdio with BM25 tool search\n- **Home Assistant Client** is an async httpx client with auth and connection pooling\n- **Cache Layer** provides TTL-based caching for states and entities\n- **Tools Layer** — 40 tools with annotations, tags, timeouts, and context logging\n- **Resources** — 5 read-only data endpoints with compact response envelopes\n- **Prompts** — 13 guided workflows for automation, troubleshooting, and optimization\n\n## License\n\nMIT\n","Home Assistant MCP Server 是一个允许AI助手通过Model Context Protocol（MCP）控制智能家居系统的服务器。该项目使用Python开发，并基于FastMCP构建，支持Claude、GPT-4、Cursor等多款AI助手。它提供了40种工具来管理家中的灯光、温控、窗帘、锁具、媒体播放器等多种设备；采用BM25算法进行工具搜索，智能错误日志解析等功能，使得操作更加高效和便捷。此外，异步处理与基于TTL的缓存机制有效减轻了API负担。适合希望利用AI助手提升家居智能化体验的场景，特别是对已有Home Assistant系统用户而言，能极大简化日常操作流程。","2026-06-11 03:58:24","CREATED_QUERY"]