ha-mcp
Comprehensive Model Context Protocol server for managing Home Assistant through AI assistants.
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"ghcr.io/homeassistant-ai/ha-mcp": {
"args": [
"run",
"-i",
"--rm",
"ghcr.io/homeassistant-ai/ha-mcp:6.5.0"
],
"command": "docker"
},
"ha-mcp": {
"args": [
"ha-mcp@6.5.0"
],
"command": "uvx"
}
}
}可用工具 （5 个）
该服务在 MCP 协议中暴露的工具，AI 可按需调用
tavily_search 14 个参数 需填 1 项
Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.
必填参数：query
tavily_extract 6 个参数 需填 1 项
Extract content from URLs. Returns raw page content in markdown or text format.
必填参数：urls
tavily_crawl 11 个参数 需填 1 项
Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.
必填参数：url
tavily_map 8 个参数 需填 1 项
Map a website's structure. Returns a list of URLs found starting from the base URL.
必填参数：url
tavily_research 2 个参数 需填 1 项
Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question or complete a task. Returns a detailed response based on the research findings.
必填参数：input
服务介绍
The Unofficial and Awesome Home Assistant MCP Server
馃殌 Get Started
Full guide to get you started with Claude Desktop (~10 min)
No paid subscription required. Click on your operating system:
Quick install (~5 min)
- Go to claude.ai and sign in (or create a free account)
- Open Terminal and run:
curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-macos.sh | sh - Download Claude Desktop (or restart: Claude menu 鈫� Quit)
- Ask Claude: "Can you see my Home Assistant?"
You're now connected to the demo environment! [Connect your own Home Assistant 鈫抅(https://homeassistant-ai.github.io/ha-mcp/guide-macos/#step-6-connect-your-home-assistant)
- Go to claude.ai and sign in (or create a free account)
- Open Windows PowerShell (from Start menu) and run:
irm https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-windows.ps1 | iex - Download Claude Desktop (or restart: File 鈫� Exit)
- Ask Claude: "Can you see my Home Assistant?"
You're now connected to the demo environment! [Connect your own Home Assistant 鈫抅(https://homeassistant-ai.github.io/ha-mcp/guide-windows/#step-6-connect-your-home-assistant)
馃 Setup Wizard for 15+ clients
Claude Code, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor, and more.
Having issues? Check the FAQ & Troubleshooting
馃挰 What Can You Do With It?
Just talk to Claude naturally. Here are some real examples:
| You Say | What Happens |
|---|---|
| "Create an automation that turns on the porch light at sunset" | Creates the automation with proper triggers and actions |
| "Add a weather card to my dashboard" | Updates your Lovelace dashboard with the new card |
| "The motion sensor automation isn't working, debug it" | Analyzes execution traces, identifies the issue, suggests fixes |
| "Make my morning routine automation also turn on the coffee maker" | Reads the existing automation, adds the new action, updates it |
| "Create a script that sets movie mode: dim lights, close blinds, turn on TV" | Creates a reusable script with the sequence of actions |
Spend less time configuring, more time enjoying your smart home.
鉁� Features
| Category | Capabilities |
|---|---|
| 馃攳 Search | Fuzzy entity search, deep config search, system overview |
| 馃彔 Control | Any service, bulk device control, real-time states |
| 馃敡 Manage | Automations, scripts, helpers, dashboards, areas, zones, groups, calendars, blueprints |
| 馃搳 Monitor | History, statistics, camera snapshots, automation traces, ZHA devices |
| 馃捑 System | Backup/restore, updates, add-ons, device registry |
| Category | Tools |
|---|---|
| Search & Discovery | ha_search_entities, ha_deep_search, ha_get_overview, ha_get_state |
| Service & Device Control | ha_call_service, ha_bulk_control, ha_get_operation_status, ha_get_bulk_status, ha_list_services |
| Automations | ha_config_get_automation, ha_config_set_automation, ha_config_remove_automation |
| Scripts | ha_config_get_script, ha_config_set_script, ha_config_remove_script |
| Helper Entities | ha_config_list_helpers, ha_config_set_helper, ha_config_remove_helper |
| Dashboards | ha_config_get_dashboard, ha_config_set_dashboard, ha_config_update_dashboard_metadata, ha_config_delete_dashboard, ha_get_dashboard_guide, ha_get_card_types, ha_get_card_documentation |
| Areas & Floors | ha_config_list_areas, ha_config_set_area, ha_config_remove_area, ha_config_list_floors, ha_config_set_floor, ha_config_remove_floor |
| Labels | ha_config_get_label, ha_config_set_label, ha_config_remove_label, ha_manage_entity_labels |
| Zones | ha_get_zone, ha_create_zone, ha_update_zone, ha_delete_zone |
| Groups | ha_config_list_groups, ha_config_set_group, ha_config_remove_group |
| Todo Lists | ha_get_todo, ha_add_todo_item, ha_update_todo_item, ha_remove_todo_item |
| Calendar | ha_config_get_calendar_events, ha_config_set_calendar_event, ha_config_remove_calendar_event |
| Blueprints | ha_list_blueprints, ha_get_blueprint, ha_import_blueprint |
| Device Registry | ha_get_device, ha_update_device, ha_remove_device, ha_rename_entity |
| ZHA & Integrations | ha_get_zha_devices, ha_get_entity_integration_source |
| Add-ons | ha_get_addon |
| Camera | ha_get_camera_image |
| History & Statistics | ha_get_history, ha_get_statistics |
| Automation Traces | ha_get_automation_traces |
| System & Updates | ha_check_config, ha_restart, ha_reload_core, ha_get_system_info, ha_get_system_health, ha_get_updates |
| Backup & Restore | ha_backup_create, ha_backup_restore |
| Utility | ha_get_logbook, ha_eval_template, ha_get_domain_docs, ha_get_integration |
馃 Better Results with Agent Skills
This server gives your AI agent tools to control Home Assistant. For better configurations, pair it with Home Assistant Agent Skills 鈥� domain knowledge that teaches the agent Home Assistant best practices.
An MCP server can create automations, helpers, and dashboards, but it has no opinion on how to structure them. Without domain knowledge, agents tend to over-rely on templates, pick the wrong helper type, or produce automations that are hard to maintain. The skills fill that gap: native constructs over Jinja2 workarounds, correct helper selection, safe refactoring workflows, and proper use of automation modes.
馃И Dev Channel
Want early access to new features and fixes? Dev releases (.devN) are published on every push to master.
Dev Channel Documentation 鈥� Instructions for pip/uvx, Docker, and Home Assistant add-on.
馃 Contributing
For development setup, testing instructions, and contribution guidelines, see CONTRIBUTING.md.
For comprehensive testing documentation, see tests/README.md.
馃敀 Privacy
Ha-mcp runs locally on your machine. Your smart home data stays on your network.
- Configurable telemetry 鈥� optional anonymous usage stats
- No personal data collection 鈥� we never collect entity names, configs, or device data
- User-controlled bug reports 鈥� only sent with your explicit approval
For full details, see our Privacy Policy.
馃搫 License
This project is licensed under the MIT License - see the LICENSE file for details.
馃檹 Acknowledgments
- Home Assistant: Amazing smart home platform (!)
- FastMCP: Excellent MCP server framework
- Model Context Protocol: Standardized AI-application communication
- Claude Code: AI-powered coding assistant
馃懃 Contributors
- @julienld 鈥� Project maintainer & core contributor.
- @kingbear2 鈥� Windows UV setup guide.
- @sergeykad 鈥� Dashboard card-level CRUD operations, better changelogs and removed the dependency to textdistance/numpy.
- @konradwalsh 鈥� Financial support via GitHub Sponsors. Thank you! 鈽�
- @cj-elevate 鈥� Integration & entity management tools (enable/disable/delete).
- @kingpanther13 鈥� Dev channel documentation, bulk control validation, OAuth 2.1 docs, tool consolidation, error handling improvements, and native solutions guidance.
- @Danm72 鈥� Entity registry tools (
ha_set_entity,ha_get_entity) for managing entity properties. - @Raygooo 鈥� SOCKS proxy support.
馃挰 Community
- GitHub Discussions 鈥� Ask questions, share ideas
- Issue Tracker 鈥� Report bugs, request features, or suggest tool behavior improvements
