Enhanced Homeassistant MCP

🚀 增强版Home Assistant MCP

增强版Home Assistant MCP是一个全面的MCP（模型上下文协议）服务器，它与Home Assistant深度集成，使AI助手能够与智能家居设备、自动化系统和系统管理进行交互，为智能家居控制带来更智能、便捷的体验。

🚀 快速开始

使用NPX快速启动

无需安装！ 直接使用npx运行：

# 设置你的Home Assistant凭证
export HOMEASSISTANT_URL="http://your-ha-ip:8123"
export HOMEASSISTANT_TOKEN="your-long-lived-access-token"

# 启动服务器
npx @thelord/enhanced-homeassistant-mcp

📖 完整的NPX使用指南 →

🚧 Smithery部署状态：目前正在优化工具加载，以防止Smithery工具扫描期间出现超时问题。详情请参阅 TIMEOUT_RESOLUTION.md。

✨ 主要特性

📊 基本操作

• ✅ API状态验证
• 📱 实体状态管理
• 🔄 带高级参数的服务调用
• 📝 实体发现和列表展示
• 🛠️ 配置信息获取

🤖 自动化与控制

• 📜 自动化管理（启用/禁用/触发）
• 🎬 场景激活
• 📜 脚本执行
• 🔘 输入布尔值控制
• 📅 定时自动化洞察

📊 历史记录与监控

• 📈 实体历史跟踪
• 📝 日志条目记录
• ⚠️ 错误日志监控
• 📡 系统事件监测
• 🔍 配置验证

🏠 设备控制

• 💡 灯光：亮度、颜色、温度控制
• 🌡️ 气候设备：温度、HVAC模式、预设控制
• 📺 媒体播放器：播放/暂停、音量、媒体选择控制
• 🏠 遮阳帘：打开/关闭、位置控制
• 📢 通知：多服务消息发送
• 🔍 设备发现：按类型/域过滤

⚙️ 系统管理

• 📊 系统信息和健康状态
• 🏷️ 模板渲染（Jinja2）
• 🏠 区域和设备管理
• 🔌 集成监控
• 🔄 系统重启功能
• 📱 管理器和插件管理
• 🔍 实体搜索和发现

📦 安装指南

前提条件

• Node.js 18+
• 具有API访问权限的Home Assistant实例
• Home Assistant的长期访问令牌

安装步骤

# 克隆仓库
git clone https://github.com/gilberth/enhanced-homeassistant-mcp.git
cd enhanced-homeassistant-mcp

# 安装依赖
npm install

# 复制环境模板
cp .env.example .env

配置

编辑 .env 文件，填入你的Home Assistant详细信息：

HOME_ASSISTANT_URL=http://homeassistant.local:8123
HOME_ASSISTANT_TOKEN=your_long_lived_access_token_here
DEBUG=false
REQUEST_TIMEOUT=10000

获取访问令牌

1. 在浏览器中打开Home Assistant
2. 转到你的个人资料（点击侧边栏中的用户名）
3. 向下滚动到“长期访问令牌”
4. 点击“创建令牌”
5. 给令牌命名并复制生成的令牌

运行服务器

选项1：NPX（推荐 - 无需安装）

# 快速启动
npx @thelord/enhanced-homeassistant-mcp

# 带选项启动
npx @thelord/enhanced-homeassistant-mcp --debug start
npx @thelord/enhanced-homeassistant-mcp inspect
npx @thelord/enhanced-homeassistant-mcp health

选项2：本地安装

# 开发模式
npm run dev

# 生产模式
npm run build
npm start

# 使用MCP检查器（用于测试）
npm run inspector

🐳 Docker部署（推荐）

使用Docker进行简单安全的部署：

# 构建镜像
docker build -t enhanced-homeassistant-mcp .

# 运行容器
docker run -d \
  --name homeassistant-mcp \
  --restart unless-stopped \
  -e HOME_ASSISTANT_URL="http://your-hass-ip:8123" \
  -e HOME_ASSISTANT_TOKEN="your_long_lived_token" \
  enhanced-homeassistant-mcp

📖 完整的Docker指南：请参阅 DOCKER.md 获取详细说明。

☁️ Smithery部署（云端）

要使用通过Smithery部署在云端的服务器：

1. 访问：Smithery.ai
2. 搜索：@gilberth/enhanced-homeassistant-mcp
3. 配置你的实例：
   • Home Assistant URL
   • 长期访问令牌
   • 可选选项（调试、超时）

// 使用Smithery SDK
import { createSmitheryUrl } from "@smithery/sdk";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const config = {
  homeAssistantToken: "your_token",
  homeAssistantUrl: "http://your-hass-ip:8123",
};

const serverUrl = createSmitheryUrl(
  "https://server.smithery.ai/@gilberth/enhanced-homeassistant-mcp",
  { config, apiKey: "your-smithery-api-key" }
);

🎯 Smithery的优势：无需基础设施配置、自动扩展和全球访问。

🛠️ 可用工具

基本工具

自动化工具

历史记录工具

设备控制工具

系统工具

💻 使用示例

基础用法

// 获取灯光状态
const lightState = await homeassistant_get_entity_state({
  entity_id: "light.living_room",
});

// 打开灯光并设置亮度和颜色
const result = await homeassistant_control_lights({
  entity_id: "light.living_room",
  action: "turn_on",
  brightness_pct: 75,
  color_name: "warm_white",
});

高级用法

自动化管理

// 列出所有自动化
const automations = await homeassistant_list_automations();

// 启用一个自动化
const enabled = await homeassistant_toggle_automation({
  entity_id: "automation.morning_routine",
  action: "turn_on",
});

// 激活一个场景
const scene = await homeassistant_activate_scene({
  entity_id: "scene.movie_time",
});

气候控制

// 设置恒温器温度
const climate = await homeassistant_control_climate({
  entity_id: "climate.living_room",
  temperature: 22,
  hvac_mode: "heat",
});

系统信息

// 获取系统概述
const systemInfo = await homeassistant_system_info();

// 搜索实体
const searchResults = await homeassistant_search_entities({
  search: "temperature",
  domain: "sensor",
});

🎮 客户端示例

在 目录中提供了可用的客户端示例：

📁 可用示例

• simple-client.js - 基本连接和工具使用
• smithery-client.js - 全功能演示
• secure-client.js - 基于环境的安全配置

🚀 快速开始示例

cd examples
npm install
cp .env.example .env
# 编辑.env文件，填入你的凭证
npm run secure

🔗 与Smithery一起使用：这些示例可直接与部署在 Smithery.ai 上的服务器配合使用。 📖 详细指南：请参阅 获取完整的设置说明。

🔧 技术细节

项目结构

src/
├── index.ts                    # 主服务器文件
├── utils/
│   └── api.ts                  # API实用工具
└── tools/
    └── homeassistant/
        ├── basic.ts            # 基本HA操作
        ├── automation.ts       # 自动化工具
        ├── history.ts          # 历史记录和监控
        ├── devices.ts          # 设备控制
        └── system.ts           # 系统管理

添加新工具

1. 在适当的工具文件中创建一个新函数
2. 使用 server.tool() 向服务器注册它
3. 遵循现有的错误处理和响应格式化模式
4. 在README中添加文档说明

测试

# 使用检查器进行交互式测试
npm run inspector

# 测试特定端点
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "http://localhost:8123/api/states"

🚑 故障排除

常见问题

连接失败

• 验证 HOME_ASSISTANT_URL 是否正确且可访问
• 检查Home Assistant是否正在运行
• 确保没有防火墙阻止连接

认证失败

• 验证你的长期访问令牌是否正确
• 检查令牌是否未过期或被撤销
• 确保令牌具有必要的权限

实体未找到

• 使用 homeassistant_list_all_entities 查找正确的实体ID
• 检查实体是否存在并在Home Assistant中启用
• 验证正确的域前缀（例如，light., sensor.）

服务调用失败

• 使用 homeassistant_list_services 验证服务是否可用
• 检查服务参数是否适合你的设备
• 某些服务需要特定的实体类型或状态

调试模式

在 .env 中启用调试日志：

DEBUG=true

🤝 贡献

1. 分叉仓库
2. 创建一个功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 打开一个拉取请求

开发指南

• 遵循现有的代码风格和模式
• 添加适当的TypeScript类型
• 为所有API调用包含错误处理
• 为新功能更新文档
• 使用真实的Home Assistant实例进行测试

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• Home Assistant - 出色的智能家居平台
• Model Context Protocol - 协议规范
• TypeScript - 编程语言和工具

📞 支持

如果遇到问题或有疑问：

1. 查看 故障排除部分
2. 搜索现有的 GitHub问题
3. 创建一个新问题，包含：
   • Home Assistant版本
   • MCP服务器日志
   • 重现步骤
   • 预期与实际行为对比

为Home Assistant社区用心打造 ❤️