智能家居控制服务器

家庭助理MCP服务器

该项目允许Claude Desktop与您的家庭助理系统进行对话。

设置完成后，您可以向Claude询问以下问题：

What lights are on?
Turn off the kitchen light.
Set the thermostat to 72.
Show me the outdoor temperature history.
Run my morning automation if it is allowed by my safety settings.

Claude通过使用Home Assistant的本地API来实现这一点。此项目中的任何内容都不会打开公共web服务器。

看 changelog.md 项目变更。

这是给谁的

在以下情况下使用此选项：

• 您使用家庭助理。
• 您使用Claude Desktop或支持MCP的其他应用程序。
• 你想让克劳德读取或控制你的智能家居设备。

这适用于：

• macOS
• Windows 11

你需要的

在开始之前，您需要：

• 家庭助理已在运行。
• Python 3已安装。
• 已安装Claude Desktop。
• 家庭助理长期访问令牌。

如果你不知道是否安装了Python，下面的设置步骤将帮助你检查。

重要安全注意事项

Claude可能能够控制你家里的真实设备，这取决于你要求它做什么以及你的家庭助理令牌有什么权限。

默认情况下，此项目会阻止敏感操作。

小心以下设备：

• 门锁
• 车库门
• 警报
• 气候控制
• 暖气
• 烤箱
• 灌溉系统
• 任何改变您家庭状态的自动化

使用来自帐户的家庭助理令牌，该帐户仅具有您愿意授予Claude的权限。

稍后可以允许敏感操作，但您应该只允许您理解和信任的设备。

第一步：下载此项目

将此项目下载或克隆到您的计算机。

例如，你可以把它放在这里：

macOS：

/Users/yourname/homeassistant-mcp

窗户：

C:\Users\yourname\homeassistant-mcp

步骤2：安装Python依赖项

在项目文件夹中打开一个终端。

在macOS上，使用终端并运行：

python3 -m pip install -r requirements.txt

在Windows 11上，使用PowerShell并运行：

py -3 -m pip install -r requirements.txt

如果此步骤显示缺少Python，请从以下位置安装Python 3 python.org 然后再试一次。

步骤3：创建家庭助理令牌

家庭助理：

1. 打开您的用户配置文件。
2. 滚动到 长寿命访问令牌.
3. 创建新令牌。
4. 给它起个明确的名字，比如 Claude MCP.
5. 复制令牌。

您只会看到一次令牌，因此请将其保存在私有位置，直到安装完成。

不要将此令牌提交到GitHub。不要公开分享。

步骤4：将其连接到克劳德桌面

最简单的方法是使用安装脚本。

macOS

在终端中，从该项目文件夹运行：

python3 setup_mcp.py --ha-url http://homeassistant.local:8123 --ha-token YOUR_TOKEN_HERE

替换 YOUR_TOKEN_HERE 使用您从家庭助理复制的令牌。

如果您的家庭助理不使用 homeassistant.local，请改用其IP地址：

python3 setup_mcp.py --ha-url http://192.168.1.100:8123 --ha-token YOUR_TOKEN_HERE

要允许一个敏感设备，请添加 --allowed-sensitive-entities.

例子：

python3 setup_mcp.py --ha-url http://homeassistant.local:8123 --ha-token YOUR_TOKEN_HERE --allowed-sensitive-entities lock.front_door

Windows 11

在PowerShell中，从该项目文件夹运行：

py -3 setup_mcp.py --ha-url http://homeassistant.local:8123 --ha-token YOUR_TOKEN_HERE

替换 YOUR_TOKEN_HERE 使用您从家庭助理复制的令牌。

如果您的家庭助理不使用 homeassistant.local，请改用其IP地址：

py -3 setup_mcp.py --ha-url http://192.168.1.100:8123 --ha-token YOUR_TOKEN_HERE

要允许一个敏感设备，请添加 --allowed-sensitive-entities.

例子：

py -3 setup_mcp.py --ha-url http://homeassistant.local:8123 --ha-token YOUR_TOKEN_HERE --allowed-sensitive-entities lock.front_door

Windows替代方案

Windows用户还可以使用附带的PowerShell脚本：

.\Set-ClaudeMcp.ps1 -HaUrl "http://homeassistant.local:8123" -HaToken "YOUR_TOKEN_HERE"

要允许一个敏感设备使用PowerShell帮助程序，请执行以下操作：

.\Set-ClaudeMcp.ps1 -HaUrl "http://homeassistant.local:8123" -HaToken "YOUR_TOKEN_HERE" -AllowedSensitiveEntities "lock.front_door"

步骤5：重新启动克劳德桌面

完全关闭Claude Desktop，然后再次打开。

重新启动后，Claude应该能够使用Home Assistant工具。

包括哪些工具

克劳德得到的工具可以：

• 阅读您的家庭助理配置。
• 列出设备和实体状态。
• 检查一个设备或传感器的状态。
• 打开、关闭或切换设备。
• 设置恒温器或气候设备温度。
• 锁定和解锁支持的锁定设备。
• 打开和关闭支撑盖，如遮阳帘、百叶窗、窗帘或车库门。
• 呼叫总部助理服务。
• 列出可用的家庭助理服务。
• 触发自动。
• 阅读一个实体的最近历史记录。
• 渲染家庭助手模板。
• 让家庭助理检查其配置。

在正常使用中，您不需要按名称调用这些工具。你通常可以用简单的英语问克劳德。

安全设置

除非您明确允许，否则敏感操作将被阻止。

默认情况下被阻止：

• 警报
• 自动化
• 气候设备
• 覆盖物，如车库门、遮阳帘、百叶窗和窗帘
• 门锁
• 加湿器
• 脚本
• 塞壬
• 阀门
• 热水器

您可以通过三种方式允许敏感操作：

您还可以阻止设备，即使它们本来是允许的：

对于大多数用户来说，最安全的选择是只允许单个实体。

例子：

HA_ALLOWED_SENSITIVE_ENTITIES=climate.hallway,cover.living_room_shades

常见问题

克劳德无法联系到家庭助理

尝试使用IP地址，而不是 homeassistant.local.

例子：

http://192.168.1.100:8123

克劳德说未经授权

您的令牌可能错误、过期或复制不正确。

在Home Assistant中创建一个新的长期访问令牌，然后再次运行安装程序。

Claude不显示家庭助理工具

请尝试以下步骤：

1. 重新启动克劳德桌面。
2. 请确保从该项目文件夹运行了安装命令。
3. 确保Python依赖项安装步骤已成功完成。
4. 再次运行安装命令。

缺少Python模块

依赖项可能已安装到不同的Python安装中。

从此项目文件夹再次运行依赖项安装命令：

macOS：

python3 -m pip install -r requirements.txt

窗户：

py -3 -m pip install -r requirements.txt

此项目中的文件

对于高级用户

安装脚本编辑Claude Desktop的MCP配置文件，并在保存更改之前创建备份。

MCP服务器入口将Claude指向 server.py 并传递这些环境变量：

如果愿意，您可以手动编辑Claude Desktop的MCP配置，但大多数用户应该使用安装脚本。

许可证

该项目根据MIT许可证获得许可。看 LICENSE 了解详情。