AI导哈

Home Assistant MCP服务器

一个用于Home Assistant的模型上下文协议（MCP）服务器，通过Streamable HTTP实现实时通信，将Home Assistant实体和服务暴露给MCP客户端（如Claude Desktop、Cursor、Antigravity等AI代理）。

  • by kaichiachen
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 kaichiachen/homeassistant-mcp-server

使用说明

家庭助理mcp服务器

一种用于家庭助理的模型上下文协议（MCP）服务器，利用流式HTTP进行实时通信。这允许您将家庭助理实体和服务暴露给MCP客户端（如Claude Desktop、Cursor、Antigravity和其他AI代理）。

特性

  • 实体管理：按域列出、搜索和筛选家庭助理实体
  • 设备控制：打开/关闭设备、切换和控制实体操作
  • 自动化和脚本：列出自动化，获取包括输入字段在内的脚本配置
  • 日历事件：查询日历事件的日期范围
  • 系统监控：获取系统概述、错误日志、实体历史记录和日志
  • 服务调用：使用自定义参数呼叫任何家庭助理服务
  • 连拱的：支持 amd64 和 aarch64 （ARM64），非常适合Raspberry Pi

可用的MCP工具

工具 说明
get_version 获取家庭助理版本
get_entity 使用可选字段筛选获取实体状态
entity_action 对实体执行开/关/切换操作
list_entities 列出具有域过滤和搜索功能的实体
search_entities_tool 按名称、ID或属性搜索实体
domain_summary_tool 获取特定域中实体的摘要
system_overview 全面了解HA系统
list_automations 列出所有带有状态和触发器的自动化
list_scripts_tool 列出所有具有可选配置的脚本
get_script_config_tool 获取脚本字段（输入）和序列（动作）
get_calendar_events_tool 获取日期范围内的日历事件
get_camera_image_tool 从相机获取静止图像
call_service_tool 呼叫任何家庭助理服务
get_history 获取实体状态更改历史记录
get_error_log 获取家庭助理错误日志
get_logbook 获取日志条目

安装

方法1：家庭助理插件（推荐）

单击下面的按钮添加存储库：

或手动：

  1. 首选 设置 > 附加组件 > 附加应用商店
  2. 点击⋮（右上角）> 仓库
  3. 添加： https://github.com/kaichiachen/homeassistant-mcp-server
  4. 找到“家庭助理mcp服务器”并单击 安装
  5. 配置 ha_url 和 ha_token 在 配置 标签
  6. 点击 开始

方法二：Docker

docker run -d \
  --name homeassistant-mcp-server \
  -p 8000:8000 \
  -e HA_URL="http://your-home-assistant-ip:8123" \
  -e HA_TOKEN="your-long-lived-access-token" \
  ghcr.io/kaichiachen/homeassistant-mcp-server:latest

配置

变量 描述 默认值
HA_URL 家庭助理URL http://localhost:8123
HA_TOKEN 长效访问令牌 必需

MCP客户端配置

一旦您的服务器正在运行（例如 http://localhost:8000)，配置您的MCP客户端：

光标

添加到 .cursor/mcp.json:

{
  "mcpServers": {
    "ha-mcp-server": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

反重力

添加到 ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "ha-mcp-server": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

克劳德桌面

添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "ha-mcp-server": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Gemini CLI

gemini --mcp-server="http://localhost:8000/mcp/"

或添加到 ~/.gemini/settings.json:

{
  "mcpServers": {
    "ha-mcp-server": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

克劳德代码（VS代码扩展）

添加到VS代码设置(settings.json):

{
  "claude.mcpServers": {
    "ha-mcp-server": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

发展

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run locally
export HA_URL="http://localhost:8123"
export HA_TOKEN="your-token"
uv run python -m app.server

# Server available at http://localhost:8000/mcp/
# Health check: http://localhost:8000/health

最佳实践

  • Unicode编码：确保所有输入字符串（实体ID、搜索查询、服务名称等）都是UTF-8编码的，以确保与家庭助理的兼容性。
  • 精益格式：除非您特别需要所有属性，否则请使用默认的精益格式进行实体检索，以节省令牌使用。
  • 域名筛选：在列出实体时，更喜欢按域过滤，以提高性能并减少响应大小。

许可证

MIT许可证-请参阅 许可证 文件。

相关 MCP