Home Assistant MCP

🚀 家庭助手 MCP 服务器

家庭助手 MCP 服务器是一个与 Home Assistant 集成的模型上下文协议 (MCP) 服务器项目，它提供了强大的智能家庭控制功能，让用户可以更便捷地管理家庭设备。

🚀 快速开始

📦 安装指南

按照说明安装 Home Assistant 并获取一个长期访问令牌。

• Home Assistant 入门指南

Claude Desktop

在 MacOS 上：~/Library/Application\ Support/Claude/claude_desktop_config.json 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json%

✨ 主要特性

提示

服务器为每个领域的工具集提供提示。

工具

服务器实现对各种 Home Assistant 领域的控制。目前支持：

• 💡 灯光：开/关，亮度调节
• 🌡️ 气候：温度控制，HVAC 模式
• 🔒 锁：上锁/解锁功能
• 🚨 报警控制面板：布防/撤防安全系统
• 💧 加湿器：湿度控制

示例工具包括：

light-turn_on()
climate-turn_off()
alarm_control_panel-disarm()
lock-lock()
humidifier-turn_off()

📚 详细文档

配置

环境变量

在根目录下创建一个 .env 文件，内容如下：

HOMEASSISTANT_TOKEN=your_long_lived_access_token_here # 在您的 Home Assistant 实例中获取长生命周期访问令牌后添加
HOMEASSISTANT_BASE_URL=your_home_assistant_url_here # 例如 http://homeassistant.local:8123

开发

构建和发布

为了准备分发包：

1. 同步依赖项并更新锁文件：

uv sync

2. 构建包分布：

uv build

这将在 dist/ 目录下创建源代码和轮分布。

3. 发布到 PyPI：

uv publish

注意：您需要通过环境变量或命令行标志设置 PyPI 凭证：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于 MCP 服务器通过标准输入输出运行，调试可能具有挑战性。为了获得最佳调试体验，我们强烈推荐使用 MCP 检查器。

您可以通过 npm 执行以下命令启动 MCP 检查器：

npx @modelcontextprotocol/inspector

贡献指南

代码规范

1. 保持代码简洁易懂。
2. 遵循项目目录结构。
3. 提交信息包含问题编号和说明。

如何贡献

1. 叉分仓库：git clone https://github.com/yourusername/home-assistant-mcp.git
2. 创建功能分支：git checkout -b feature/problemNumber
3. 提交更改：git commit -m "feat: 问题描述"
4. 推送到远程仓库：git push origin feature/problemNumber
5. 创建拉取请求。

依赖管理

使用 package.json 管理项目依赖，安装依赖时运行：

npm install

📄 许可证

MIT License