MCP Homeassistant

家庭助理MCP服务器

  

一个模型上下文协议（MCP）服务器，使像克劳德这样的人工智能助手能够与家庭助理进行交互。通过标准化的AI到家庭自动化界面控制智能家居设备、管理自动化、查询实体状态等。

特性

核心能力

• 实体国家管理：查询任何家庭助理实体的当前状态和属性
• 实体发现：按域列出和过滤实体（灯、传感器、开关等）
• 服务呼叫：执行任何家庭助理服务来控制设备
• 历史数据：检索可配置时间段内的实体状态历史记录
• 自动化触发器：手动触发自动

自动化管理

• 创建自动化：从YAML配置构建新的自动化
• 更新自动化：修改现有自动化配置
• 删除自动化：以编程方式删除自动化
• 视图配置：检索任何自动化的完整YAML配置
• 列出所有自动化：获取自动化配置的完整清单
• 重新加载自动化：更改后刷新自动化配置
• 启用/禁用：打开或关闭自动功能

可用工具（13）

安装

先决条件

• Python 3.10或更高版本
• 家庭助理实例（本地或远程）
• 家庭助理长期访问令牌

设置步骤

1. 克隆仓库

   git clone https://github.com/mjrestivo16/mcp-homeassistant.git
   cd mcp-homeassistant

1. 创建虚拟环境

   python -m venv venv

   # On Windows
   venv\Scripts\activate

   # On Linux/Mac
   source venv/bin/activate

1. 安装依赖项

   pip install -r requirements.txt

1. 配置环境

创建一个 .env 项目根目录中的文件：

   HA_URL=http://192.168.1.100:8123
   HA_TOKEN=your_long_lived_access_token_here

要生成长效访问令牌，请执行以下操作：

1. 登录家庭助理 1. 点击您的个人资料（左下角） 1. 滚动到“长期访问令牌” 1. 点击“创建令牌” 1. 为其命名（例如，“MCP服务器”） 1. 将令牌复制到您的 .env 文件

1. 测试服务器

   python server.py

Claude桌面配置

将此配置添加到您的Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "homeassistant": {
      "type": "stdio",
      "command": "python",
      "args": ["C:/path/to/mcp-homeassistant/server.py"],
      "env": {
        "HA_URL": "http://192.168.1.100:8123",
        "HA_TOKEN": "your_long_lived_access_token_here"
      }
    }
  }
}

备注：在配置中使用绝对路径。添加配置后重新启动Claude Desktop。

使用示例

查询实体状态

# Ask Claude:
"What's the current state of my living room light?"

# Claude uses: get_state("light.living_room")

控制装置

# Ask Claude:
"Turn on the bedroom light at 50% brightness"

# Claude uses: call_service(
#   domain="light",
#   service="turn_on",
#   entity_id="light.bedroom",
#   data={"brightness_pct": 50}
# )

创建自动化

# Ask Claude:
"Create an automation that turns on the porch light at sunset"

# Claude uses: create_automation({
#   "id": "porch_light_sunset",
#   "alias": "Porch Light at Sunset",
#   "trigger": {
#     "platform": "sun",
#     "event": "sunset"
#   },
#   "action": {
#     "service": "light.turn_on",
#     "target": {"entity_id": "light.porch"}
#   }
# })

按域列出实体

# Ask Claude:
"Show me all my temperature sensors"

# Claude uses: list_entities(domain="sensor")
# Then filters results for temperature entities

查看自动化历史记录

# Ask Claude:
"Show me the history of my thermostat for the last 12 hours"

# Claude uses: get_history(
#   entity_id="climate.living_room",
#   hours=12
# )

api参考

get_state

获取任何家庭助理实体的当前状态和属性。

参数：

• entity_id （string，必填）：实体ID（例如。， light.office, sensor.temperature)

退货： 带有实体状态和所有属性的格式化文本

例子：

{
  "entity_id": "light.living_room"
}

______________________________________________________________________

list_entities

列出所有实体，可选择按域筛选。

参数：

• domain （字符串，可选）：域过滤器（例如。， light, sensor, automation)

退货： 实体及其当前状态列表（仅限于前50个）

例子：

{
  "domain": "light"
}

______________________________________________________________________

呼叫服务

呼叫任何家庭助理服务来控制设备。

参数：

• domain （string，必填）：服务域（例如。， light, climate, switch)
• service （string，必填）：服务名称（例如。， turn_on, turn_off, set_temperature)
• entity_id （字符串，必填）：目标实体ID
• data （对象，可选）：附加服务数据（例如亮度、温度）

退货： 成功确认消息

例子：

{
  "domain": "light",
  "service": "turn_on",
  "entity_id": "light.bedroom",
  "data": {
    "brightness_pct": 75,
    "color_temp": 370
  }
}

______________________________________________________________________

触发器_自动

手动触发家庭助理自动化。

参数：

• entity_id （string，必填）：自动化实体ID（例如。， automation.morning_routine)

退货： 成功确认消息

例子：

{
  "entity_id": "automation.morning_routine"
}

______________________________________________________________________

获取历史

获取实体的历史状态更改。

参数：

• entity_id （字符串，必填）：用于获取历史记录的实体ID
• hours （数字，可选）：历史小时数（默认值：24）

退货： 该时间段内最近10次状态更改

例子：

{
  "entity_id": "sensor.outdoor_temperature",
  "hours": 12
}

______________________________________________________________________

创建_自动化

从YAML配置创建新的家庭助理自动化。

参数：

• automation_config （对象，必填）：完整的自动化配置，包括：

- id （字符串，必填）：唯一自动化ID - alias （字符串，必填）：人类可读名称 - trigger （对象/数组，必填）：触发器配置 - action （对象/数组，必填）：操作配置 - condition （对象/数组，可选）：条件配置 - mode （字符串，可选）：自动化模式（单次、重启、排队、并行）

退货： 使用自动化ID确认成功

例子：

{
  "automation_config": {
    "id": "motion_light_kitchen",
    "alias": "Kitchen Motion Light",
    "trigger": {
      "platform": "state",
      "entity_id": "binary_sensor.kitchen_motion",
      "to": "on"
    },
    "action": {
      "service": "light.turn_on",
      "target": {"entity_id": "light.kitchen"}
    }
  }
}

______________________________________________________________________

update_自动化

更新现有的家庭助理自动化。

参数：

• automation_id （string，必填）：自动化ID（不是entity_ID）
• automation_config （对象，必填）：更新的自动化配置

退货： 使用自动化ID确认成功

例子：

{
  "automation_id": "motion_light_kitchen",
  "automation_config": {
    "id": "motion_light_kitchen",
    "alias": "Kitchen Motion Light (Updated)",
    "trigger": {
      "platform": "state",
      "entity_id": "binary_sensor.kitchen_motion",
      "to": "on"
    },
    "action": [
      {
        "service": "light.turn_on",
        "target": {"entity_id": "light.kitchen"},
        "data": {"brightness_pct": 100}
      }
    ]
  }
}

______________________________________________________________________

删除_自动化

删除家庭助理自动化。

参数：

• automation_id （string，必填）：要删除的自动化ID（不是entity_ID）

退货： 成功确认

例子：

{
  "automation_id": "old_automation_id"
}

______________________________________________________________________

get_automation_config

获取自动化的完整YAML配置。

参数：

• automation_id （string，必填）：自动化ID（不是entity_ID）

退货： JSON格式的全自动配置

例子：

{
  "automation_id": "motion_light_kitchen"
}

______________________________________________________________________

list_automation_config

列出所有自动化配置（完整的YAML配置，而不仅仅是状态）。

参数： 无

退货： 所有自动化及其ID和别名的列表

______________________________________________________________________

reload \_自动

更改后重新加载所有自动化。

参数： 无

退货： 成功确认

______________________________________________________________________

启用_自动化

启用已禁用的自动化。

参数：

• entity_id （string，必填）：自动化实体ID（例如。， automation.morning_routine)

退货： 成功确认

例子：

{
  "entity_id": "automation.morning_routine"
}

______________________________________________________________________

禁用_自动化

禁用主动自动化。

参数：

• entity_id （string，必填）：自动化实体ID（例如。， automation.morning_routine)

退货： 成功确认

例子：

{
  "entity_id": "automation.morning_routine"
}

建筑

技术栈

• Python 3.10+：核心运行时
• MCP SDK 1.21.2：模型上下文协议实现
• httpx：用于Home Assistant API的异步HTTP客户端
• python dotenv：环境配置管理

通信流

Claude Desktop → MCP Server (stdio) → Home Assistant API (REST)

1. Claude Desktop通过stdio发送工具调用
2. MCP服务器处理请求并使用HA令牌进行身份验证
3. Home Assistant API执行命令并返回结果
4. MCP服务器为Claude格式化响应

错误处理

• 来自Home Assistant API的HTTP状态错误
• 请求超时（默认30秒）
• 身份验证失败
• 自动化配置格式错误

故障排除

服务器无法启动

• 验证Python版本： python --version （必须为3.10+）
• 检查虚拟环境是否已激活
• 确保安装了所有依赖项： pip install -r requirements.txt

身份验证错误

• 验证家庭助理URL是否正确且可访问
• 带有curl的测试令牌：

  curl -H "Authorization: Bearer YOUR_TOKEN" http://YOUR_HA_URL/api/

• 如果令牌过期，则重新生成令牌

工具未出现在Claude中

• 配置更改后重新启动Claude Desktop
• 检查克劳德桌面日志（帮助→ 查看日志）
• 验证配置中的绝对路径
• 确保配置文件中没有JSON语法错误

自动化更改未生效

• 使用 reload_automations 创建/更新自动化后的工具
• 检查Home Assistant日志中的YAML语法错误
• 验证自动化ID是否唯一

安全注意事项

• 永不承诺 .env 文件 到版本控制
• 安全地存储家庭助理令牌
• 在生产部署中使用网络隔离
• 考虑启用家庭助理身份验证日志
• 定期轮换访问令牌

贡献

欢迎投稿！请随时提交拉取请求。

开发设置

git clone https://github.com/mjrestivo16/mcp-homeassistant.git
cd mcp-homeassistant
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• 建立在 模型上下文协议
• 与集成 家庭助手
• 受到家庭助理社区的启发

支持

• 问题:
• 家庭助理社区: 家庭助理论坛
• MCP文件: MCP文件

______________________________________________________________________

由家庭助理社区制作