Hass-MCP
Hass-MCP
用于 Home Assistant 与 Claude 和其他 LLM 集成的模型上下文协议 (MCP) 服务器。
概述
Hass-MCP 使 Claude 等 AI 助手能够直接与您的 Home Assistant 实例进行交互,从而使他们能够:
查询设备和传感器的状态
控制灯、开关和其他实体
获取智能家居的摘要
自动化和实体故障排除
搜索特定实体
为常见任务创建引导式对话
Related MCP server: Home Assistant MCP Server
截图
特征
实体管理:获取状态、控制设备和搜索实体
领域摘要:获取有关实体类型的高级信息
自动化支持:列出并控制自动化
引导式对话:使用提示执行常见任务,例如创建自动化
智能搜索:按名称、类型或状态查找实体
令牌效率:精简 JSON 响应以最大限度地减少令牌使用
安装
先决条件
具有长效访问令牌的 Home Assistant 实例
以下之一:
Docker(推荐)
Python 3.13+ 和uv
使用 Claude Desktop 进行设置
Docker 安装(推荐)
拉取 Docker 镜像:
docker pull voska/hass-mcp:latest将 MCP 服务器添加到 Claude Desktop:
a. 打开 Claude Desktop 并转到“设置” b. 导航至“开发人员”>“编辑配置” c. 将以下配置添加到您的
claude_desktop_config.json文件:{ "mcpServers": { "hass-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "HA_URL", "-e", "HA_TOKEN", "voska/hass-mcp" ], "env": { "HA_URL": "http://homeassistant.local:8123", "HA_TOKEN": "YOUR_LONG_LIVED_TOKEN" } } } }d. 将
YOUR_LONG_LIVED_TOKEN替换为您的实际 Home Assistant 长期访问令牌 e. 更新HA_URL:如果在同一台机器上运行 Home Assistant:使用
http://host.docker.internal:8123(Mac/Windows 上的 Docker Desktop)如果在另一台机器上运行 Home Assistant:使用实际的 IP 或主机名
f.保存文件并重新启动Claude Desktop
“Hass-MCP”工具现在应该出现在您的 Claude Desktop 工具菜单中
注意:如果您在同一台机器上的 Docker 中运行 Home Assistant,则可能需要在 Docker 参数中添加
--network host,以便容器能够访问 Home Assistant。或者,使用您机器的 IP 地址,而不是host.docker.internal。
其他 MCP 客户端
光标
前往“光标设置”>“MCP”>“添加新的 MCP 服务器”
填写表格:
名称:
Hass-MCP类型:
command命令:
docker run -i --rm -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN voska/hass-mcp将
YOUR_LONG_LIVED_TOKEN替换为你的实际 Home Assistant 令牌更新 HA_URL 以匹配您的 Home Assistant 实例地址
点击“添加”保存
克劳德代码(CLI)
要与 Claude Code CLI 一起使用,您可以使用mcp add命令直接添加 MCP 服务器:
使用 Docker(推荐):
claude mcp add hass-mcp -e HA_URL=http://homeassistant.local:8123 -e HA_TOKEN=YOUR_LONG_LIVED_TOKEN -- docker run -i --rm -e HA_URL -e HA_TOKEN voska/hass-mcp将YOUR_LONG_LIVED_TOKEN替换为您的实际 Home Assistant 令牌,并更新 HA_URL 以匹配您的 Home Assistant 实例地址。
使用示例
设置好 Hass-MCP 后,您可以与 Claude 一起使用以下提示的一些示例:
“我客厅的灯现在怎么样?”
“把厨房里的灯都关掉”
“列出所有包含温度数据的传感器”
“给我一份我的气候实体的摘要”
“创建一个在日落时打开灯的自动化装置”
“帮我解决卧室运动传感器自动化系统无法工作的问题”
“搜索与我的客厅相关的实体”
可用工具
Hass-MCP 提供了几种与 Home Assistant 交互的工具:
get_version:获取 Home Assistant 版本get_entity:使用可选字段过滤获取特定实体的状态entity_action:对实体执行操作(打开、关闭、切换)list_entities:获取具有可选域过滤和搜索的实体列表search_entities_tool:搜索与查询匹配的实体domain_summary_tool:获取域实体的摘要list_automations:获取所有自动化的列表call_service_tool:调用任何 Home Assistant 服务restart_ha:重启 Home Assistantget_history:获取实体的状态历史记录get_error_log:获取 Home Assistant 错误日志
引导式对话提示
Hass-MCP 包含几个引导对话的提示:
create_automation:基于触发器类型创建 Home Assistant 自动化的指南debug_automation:针对无法正常工作的自动化的故障排除帮助troubleshoot_entity:诊断实体问题routine_optimizer:分析使用模式并根据实际行为建议优化例程automation_health_check:审查所有自动化,发现冲突、冗余或改进机会entity_naming_consistency:审核实体名称并提出标准化改进建议dashboard_layout_generator:根据用户偏好和使用模式创建优化的仪表板
可用资源
Hass-MCP 提供以下资源端点:
hass://entities/{entity_id}:获取特定实体的状态hass://entities/{entity_id}/detailed:获取有关实体的所有属性的详细信息hass://entities:列出按域分组的所有 Home Assistant 实体hass://entities/domain/{domain}:获取特定域的实体列表hass://search/{query}/{limit}:搜索与自定义结果限制匹配的查询的实体
发展
运行测试
uv run pytest tests/执照
Available Tools
29 toolsadd_cardA
Add a card to a dashboard view (live)
Args:
url_path: Dashboard URL path, or None for the default dashboard.
view: Target view — an integer index, or a string matching the view's
path or title.
card: The card config dict (must include a string type), e.g.
{"type": "markdown", "content": "Hello"}.
position: Insert index within the target card list (default: append).
section: For a "sections"-type view, which section to add into — an
index, section title, or heading text. REQUIRED for sections
views (use list_view_sections to see them); omit for classic
views.
dry_run: Preview without saving.
Returns:
Save result with a backup_id, or a dry-run preview.
Inputs: card, view, dry_run, section, +2 more. Returns: result
add_viewA
Add a new view to a dashboard (live)
Args: url_path: Dashboard URL path, or None for the default dashboard. view_config: The view config dict, e.g. {"title": "Garage", "path": "garage"}. position: Insert index among views (default: append). dry_run: Preview without saving.
Returns:
Save result with a backup_id, or a dry-run preview.
Inputs: dry_run, position, url_path, view_config. Returns: result
call_service_toolA
Call any Home Assistant service (low-level API access)
Args: domain: The domain of the service (e.g., 'light', 'switch', 'automation') service: The service to call (e.g., 'turn_on', 'turn_off', 'toggle') data: Optional data to pass to the service (e.g., {'entity_id': 'light.living_room'})
Returns: A dictionary with success status, the domain/service called, and the list of affected entity states returned by Home Assistant.
Examples: domain='light', service='turn_on', data={'entity_id': 'light.x', 'brightness': 255} domain='automation', service='reload' domain='fan', service='set_percentage', data={'entity_id': 'fan.x', 'percentage': 50}
Inputs: domain (required), service (required), data. Returns: result
domain_summary_toolA
Get a summary of entities in a specific domain
Args: domain: The domain to summarize (e.g., 'light', 'switch', 'sensor') example_limit: Maximum number of examples to include for each state
Returns: A dictionary containing: - total_count: Number of entities in the domain - state_distribution: Count of entities in each state - examples: Sample entities for each state - common_attributes: Most frequently occurring attributes
Examples: domain="light" - get light summary domain="climate", example_limit=5 - climate summary with more examples Best Practices: - Use this before retrieving all entities in a domain to understand what's available
Inputs: domain (required), example_limit. Returns: result
entity_actionA
Perform an action on a Home Assistant entity (on, off, toggle)
Args: entity_id: The entity ID to control (e.g. 'light.living_room') action: The action to perform ('on', 'off', 'toggle') params: Optional dictionary of additional parameters for the service call
Returns: The response from Home Assistant
Examples: entity_id="light.living_room", action="on", params={"brightness": 255} entity_id="switch.garden_lights", action="off" entity_id="climate.living_room", action="on", params={"temperature": 22.5}
Domain-Specific Parameters: - Lights: brightness (0-255), color_temp, rgb_color, transition, effect - Covers: position (0-100), tilt_position - Climate: temperature, target_temp_high, target_temp_low, hvac_mode - Media players: source, volume_level (0-1)
Inputs: action (required), entity_id (required), params.
get_dashboard_configA
Get a dashboard's full configuration
Args: url_path: The dashboard's URL path (e.g. "my-dash"). Omit or pass None for the default "Overview" dashboard.
Returns:
The dashboard config dict (a top-level views list of cards). If the
dashboard has no stored config yet, returns an empty {"views": []}
scaffold with a note.
Inputs: url_path. Returns: result
get_entities_by_areaA
Get all entities assigned to a specific Home Assistant area (room).
Area lookup is case-insensitive and matches the area's name as configured in Home Assistant (e.g., "Kitchen", "Living Room"). Entities inherit their area from their parent device when no area is set directly, matching HA's own resolution behavior.
Args: area: Name of the area to filter by (case-insensitive) domain: Optional domain to further filter results (e.g., 'light') lean: If True (default), returns token-efficient entity records
Returns: A dictionary containing: - area: The matched area name (as canonicalized by HA) - count: Number of matching entities - entities: List of entity records with their state and area
Examples: get_entities_by_area(area="Kitchen") - everything in the kitchen get_entities_by_area(area="Living Room", domain="light") - lights only
Inputs: area (required), lean, domain. Returns: result
get_entityA
Get the state of a Home Assistant entity with optional field filtering
Args: entity_id: The entity ID to get (e.g. 'light.living_room') fields: Optional list of fields to include (e.g. ['state', 'attr.brightness']) detailed: If True, returns all entity fields without filtering
Examples: entity_id="light.living_room" - basic state check entity_id="light.living_room", fields=["state", "attr.brightness"] - specific fields entity_id="light.living_room", detailed=True - all details
Inputs: entity_id (required), fields, detailed.
get_error_logA
Get the Home Assistant error log for troubleshooting.
All filters are optional and combine (AND semantics). Stats (error_count, warning_count, integration_mentions, total_lines) are computed over the filtered output so they match what's returned.
Args:
level: Filter to lines containing this log level — ERROR, WARNING,
INFO, or DEBUG. Case-insensitive.
integration: Filter to lines mentioning this integration. Matches
[name] or [homeassistant.components.name].
Case-insensitive.
search_term: Case-insensitive substring filter applied per line.
Useful for entity IDs, exception names, etc.
lines: Return only the most recent N lines (applied after other
filters). Useful when you only care about the tail.
Returns: A dictionary containing: - log_text: The (possibly filtered) error log text - error_count: Number of ERROR entries in the filtered output - warning_count: Number of WARNING entries in the filtered output - integration_mentions: Map of integration names to mention counts - total_lines: Number of lines in the filtered output - filters_applied: Map of which filter args were supplied - error: Error message if retrieval failed
Examples: get_error_log() # full log get_error_log(level="ERROR") # errors only get_error_log(integration="zwave_js") # one integration get_error_log(search_term="light.kitchen") # specific entity get_error_log(level="ERROR", lines=50) # last 50 errors
Best Practices:
- Filter on the server side (here) rather than pulling the full
log into Claude's context — saves tokens on noisy logs.
- Combine integration + level="ERROR" to triage a single
integration that's misbehaving.
- Use lines to bound output when scanning a long-running HA.
Inputs: level, lines, integration, search_term. Returns: result
get_historyA
Get the history of an entity's state changes
Args: entity_id: The entity ID to get history for hours: Number of hours of history to retrieve (default: 24)
Returns: A dictionary containing: - entity_id: The entity ID requested - states: List of state objects with timestamps - count: Number of state changes found - first_changed: Timestamp of earliest state change - last_changed: Timestamp of most recent state change
Examples: entity_id="light.living_room" - get 24h history entity_id="sensor.temperature", hours=168 - get 7 day history Best Practices: - Keep hours reasonable (24-72) for token efficiency - Use for entities with discrete state changes rather than continuously changing sensors - Consider the state distribution rather than every individual state
Inputs: entity_id (required), hours. Returns: result
get_history_rangeA
Get raw state-change history for an entity over a date/time range.
Like get_history, but takes an explicit window instead of "N hours
from now". Useful for inspecting what happened on a specific day or
correlating with an external event.
Args:
entity_id: The entity to fetch history for.
start_time: ISO-8601 start (e.g. 2026-05-15 or
2026-05-15T08:00:00Z). Treated as UTC if no offset.
end_time: ISO-8601 end. Defaults to now (UTC).
Returns:
Same shape as get_history: entity_id, states, count,
first_changed, last_changed.
Examples: get_history_range("light.kitchen", "2026-05-15") get_history_range("sensor.power", "2026-05-15T00:00:00Z", "2026-05-16T00:00:00Z")
Best Practices:
- Bound the window — wider ranges return more data and more tokens.
- For aggregated long-term data, prefer get_statistics_range.
Inputs: entity_id (required), start_time (required), end_time. Returns: result
get_statisticsA
Get long-term aggregated statistics for an entity over the last N hours.
Uses HA's recorder statistics (over WebSocket) — aggregated buckets
(mean / min / max per period) that survive the short-term retention
window. Use this instead of get_history when:
- You want data older than the recorder's default 10-day window.
- You want aggregated values rather than every individual change.
- The entity is a high-frequency sensor (temperature, power) and
raw history would be too many tokens.
Args:
entity_id: The entity (must have a state_class HA records as
statistics — measurement, total, total_increasing).
hours: How far back from now. Defaults to 24.
period: Bucket size — 5minute, hour, day, week, month.
Defaults to hour.
Returns:
entity_id, period, start_time, end_time, statistics
(list of {start, end, mean, min, max, ...} points).
Examples: get_statistics("sensor.power_usage", hours=168, period="day") get_statistics("sensor.temperature", hours=24)
Inputs: entity_id (required), hours, period. Returns: result
get_statistics_rangeA
Get long-term aggregated statistics for an entity over a date/time range.
Same data source as get_statistics, but with an explicit window —
useful for "what was my power usage from Jan 1 to Jan 31?" type
questions. Aggregated bucket data survives the short-term retention
window, so this works for data months/years old.
Args:
entity_id: The entity (must be statistics-tracked).
start_time: ISO-8601 start (2026-01-01 or
2026-01-01T00:00:00Z). UTC if no offset.
end_time: ISO-8601 end. Defaults to now.
period: 5minute, hour, day, week, or month.
Returns:
entity_id, period, start_time, end_time, statistics.
Examples: get_statistics_range("sensor.energy", "2026-01-01", "2026-02-01", period="day") get_statistics_range("sensor.temperature", "2026-05-01", period="hour")
Inputs: entity_id (required), start_time (required), period, end_time. Returns: result
get_versionA
Get the Home Assistant version
Returns: A string with the Home Assistant version (e.g., "2025.3.0")
Inputs: no named parameters. Returns: result
list_automationsA
Get a list of all automations from Home Assistant
This function retrieves all automations configured in Home Assistant, including their IDs, entity IDs, state, and display names.
Returns: A list of automation dictionaries, each containing id, entity_id, state, and alias (friendly name) fields.
Examples: Returns all automation objects with state and friendly names
Inputs: no named parameters. Returns: result
list_dashboard_backupsA
List on-disk backups of a dashboard's config
Backups are written automatically before every dashboard write. NOTE: in Docker, backups persist only if HASS_MCP_BACKUP_DIR is volume-mounted.
Args: url_path: Dashboard URL path, or None for the default dashboard.
Returns: A list of {backup_id, path}, oldest first.
Inputs: url_path. Returns: result
list_dashboardsA
List Home Assistant dashboards (Lovelace)
Returns:
A list of dashboards. Each entry has url_path (None for the default
"Overview" dashboard), title, and mode ("storage" or "yaml"). Only
"storage"-mode dashboards can be edited via these tools.
Inputs: no named parameters. Returns: result
list_entitiesA
Get a list of Home Assistant entities with optional filtering
Args: domain: Optional domain to filter by (e.g., 'light', 'switch', 'sensor') search_query: Optional search term to filter entities by name, id, or attributes (Note: Does not support wildcards. To get all entities, leave this empty) limit: Maximum number of entities to return (default: 100) fields: Optional list of specific fields to include in each entity detailed: If True, returns all entity fields without filtering
Returns: A list of entity dictionaries with lean formatting by default
Examples: domain="light" - get all lights search_query="kitchen", limit=20 - search entities domain="sensor", detailed=True - full sensor details
Best Practices: - Use lean format (default) for most operations - Prefer domain filtering over no filtering - For domain overviews, use domain_summary_tool instead of list_entities - Only request detailed=True when necessary for full attribute inspection - To get all entity types/domains, use list_entities without a domain filter, then extract domains from entity_ids
Inputs: limit, domain, fields, detailed, +1 more. Returns: result
list_view_sectionsA
List the sections of a "sections"-type dashboard view
Modern Home Assistant views of type: sections hold their cards inside
sections (not a top-level card list). Use this to discover which section
to target with the card tools' section argument.
Args:
url_path: Dashboard URL path, or None for the default dashboard.
view: Target view (index, or matching path/title).
Returns: A list of {index, title, heading, card_count}, one per section. Errors if the view is not a sections view.
Inputs: view, url_path. Returns: result
move_cardB
Reorder a card within a dashboard view (live)
Args:
url_path: Dashboard URL path, or None for the default dashboard.
view: Target view (index, or matching path/title).
card_index: Current index of the card.
new_index: Destination index within the same card list.
section: For a "sections"-type view, which section the card is in
(index/title/heading). Required for sections views.
dry_run: Preview without saving.
Returns:
Save result with a backup_id, or a dry-run preview.
Inputs: view, dry_run, section, url_path, +2 more. Returns: result
remove_cardA
Remove a card from a dashboard view (live)
Args:
url_path: Dashboard URL path, or None for the default dashboard.
view: Target view (index, or matching path/title).
card_index: Index of the card to remove within the target card list.
section: For a "sections"-type view, which section the card is in
(index/title/heading). Required for sections views.
dry_run: Preview without saving.
Returns:
Save result with a backup_id, or a dry-run preview.
Inputs: view, dry_run, section, url_path, +1 more. Returns: result
remove_viewA
Remove a view from a dashboard (live)
⚠️ Removes the view and all its cards.
Args:
url_path: Dashboard URL path, or None for the default dashboard.
view: Target view (index, or matching path/title).
dry_run: Preview without saving.
Returns:
Save result with a backup_id, or a dry-run preview.
Inputs: view, dry_run, url_path. Returns: result
restart_haA
Restart Home Assistant
⚠️ WARNING: Temporarily disrupts all Home Assistant operations
Returns: Result of restart operation
Inputs: no named parameters. Returns: result
restore_dashboardA
Restore a dashboard from a backup (live)
Restores the most recent backup unless backup_id is given. The current
config is itself backed up first, so a restore can be undone.
Args: url_path: Dashboard URL path, or None for the default dashboard. backup_id: A specific backup id from list_dashboard_backups (default: newest). dry_run: Preview without saving.
Returns:
Save result plus restored_from, or a dry-run preview.
Inputs: dry_run, url_path, backup_id. Returns: result
search_entities_toolA
Search for entities matching a query string
Args: query: The search query to match against entity IDs, names, and attributes. (Note: Does not support wildcards. To get all entities, leave this blank or use list_entities tool) limit: Maximum number of results to return (default: 20)
Returns: A dictionary containing search results and metadata: - count: Total number of matching entities found - results: List of matching entities with essential information - domains: Map of domains with counts (e.g. {"light": 3, "sensor": 2})
Examples: query="temperature" - find temperature entities query="living room", limit=10 - find living room entities query="", limit=500 - list all entity types
Inputs: query (required), limit. Returns: result
set_dashboard_configA
Replace a dashboard's full configuration (low-level write)
⚠️ WARNING: Overwrites the ENTIRE dashboard and updates every open browser live. The prior config is backed up first (use restore_dashboard to undo). Requires an admin token; only storage-mode dashboards can be saved.
Args:
url_path: Dashboard URL path, or None for the default dashboard.
config: The complete new config dict (must contain a views list).
dry_run: If True, validate and return the resulting config + a change
summary WITHOUT saving.
Returns: On save: {success, url_path, backup_id, summary}. On dry_run: {dry_run: True, url_path, summary, config}.
Inputs: config, dry_run, url_path. Returns: result
system_overviewA
Get a comprehensive overview of the entire Home Assistant system
Returns: A dictionary containing: - total_entities: Total count of all entities - domains: Dictionary of domains with their entity counts and state distributions - domain_samples: Representative sample entities for each domain (2-3 per domain) - domain_attributes: Common attributes for each domain - area_distribution: Entities grouped by area (if available)
Examples: Returns domain counts, sample entities, and common attributes Best Practices: - Use this as the first call when exploring an unfamiliar Home Assistant instance - Perfect for building context about the structure of the smart home - After getting an overview, use domain_summary_tool to dig deeper into specific domains
Inputs: no named parameters. Returns: result
update_cardB
Replace a card in a dashboard view (live)
Args:
url_path: Dashboard URL path, or None for the default dashboard.
view: Target view (index, or matching path/title).
card_index: Index of the card to replace within the target card list.
card: The new card config dict (must include a string type).
section: For a "sections"-type view, which section the card is in
(index/title/heading). Required for sections views.
dry_run: Preview without saving.
Returns:
Save result with a backup_id, or a dry-run preview.
Inputs: card, view, dry_run, section, +2 more. Returns: result
update_viewA
Update a view's properties — title, path, icon, etc. (live)
Cards in the view are preserved unless changes includes a cards key.
Args:
url_path: Dashboard URL path, or None for the default dashboard.
view: Target view (index, or matching path/title).
changes: Dict of view properties to merge in, e.g. {"title": "New Title"}.
dry_run: Preview without saving.
Returns:
Save result with a backup_id, or a dry-run preview.
Inputs: view, changes, dry_run, url_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Most tools target distinct resources, but several overlap: entity_action vs call_service_tool both invoke services (the former is just a convenience wrapper), and list_entities (with its search_query param) vs search_entities_tool both perform entity search. The detailed descriptions cross-reference each other and help steer the agent, but a few genuine selection ambiguities remain.
The majority follow a clean verb_noun pattern (list_dashboards, add_card, remove_view, get_history, get_statistics). However, three tools carry inconsistent _tool suffixes (domain_summary_tool, search_entities_tool, call_service_tool) and a few use noun-first names (entity_action, system_overview) or bare verbs (restart_ha), breaking the otherwise consistent convention.
At 29 tools this is heavy, and 13 of them are dashboard/Lovelace operations (card/view CRUD plus backups) that dominate the surface. While each dashboard operation is distinct, the overall set is well past the comfortable 3-15 range and several card/view tools could arguably be consolidated.
Coverage for entities, history/statistics, services, dashboards, and system diagnostics is strong end-to-end. Gaps exist around automations (only list_automations, no create/edit/trigger), scripts, scenes, and area listing, but call_service_tool provides a general escape hatch so agents can work around these.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseBqualityCmaintenanceA server that enables interaction with Home Assistant devices and automations through the Model Context Protocol, allowing users to monitor device states, control devices, trigger automations, and list entities.448MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that integrates with Home Assistant to provide smart home control capabilities through natural language, supporting devices like lights, climate systems, locks, alarms, and humidifiers.3MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows large language models to control and query Home Assistant smart home systems through natural language interactions.28 npm5MIT
- AlicenseAqualityCmaintenanceA self-hosted MCP server for Home Assistant that exposes full control over entity states, service calls, history, templates, and areas via local stdio, enabling AI assistants to manage your smart home.9108 npmMIT