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的优势：无需基础设施配置、自动扩展和全球访问。

🛠️ 可用工具

基本工具

| 工具名称 | 描述 | 参数 | | ---- | ---- | ---- | | homeassistant_api_status | 检查API连接性 | 无 | | homeassistant_get_entity_state | 获取实体状态 | entity_id | | homeassistant_list_all_entities | 列出所有实体 | domain（可选） | | homeassistant_call_service | 调用HA服务 | domain, service, entity_id, service_data | | homeassistant_list_services | 列出可用服务 | domain（可选） | | homeassistant_get_config | 获取HA配置 | 无 |

自动化工具

| 工具名称 | 描述 | 参数 | | ---- | ---- | ---- | | homeassistant_list_automations | 列出所有自动化 | 无 | | homeassistant_toggle_automation | 启用/禁用自动化 | entity_id, action | | homeassistant_trigger_automation | 触发自动化 | entity_id | | homeassistant_list_scenes | 列出所有场景 | 无 | | homeassistant_activate_scene | 激活场景 | entity_id | | homeassistant_list_scripts | 列出所有脚本 | 无 | | homeassistant_run_script | 运行脚本 | entity_id | | homeassistant_list_input_booleans | 列出输入布尔值 | 无 | | homeassistant_toggle_input_boolean | 切换输入布尔值 | entity_id, action |

历史记录工具

| 工具名称 | 描述 | 参数 | | ---- | ---- | ---- | | homeassistant_get_entity_history | 获取实体历史记录 | entity_id, start_time, end_time, minimal_response | | homeassistant_get_logbook | 获取日志条目 | entity_id, start_time, end_time | | homeassistant_get_events | 列出事件类型 | 无 | | homeassistant_get_error_log | 获取错误日志 | 无 | | homeassistant_check_config | 验证配置 | 无 |

设备控制工具

| 工具名称 | 描述 | 参数 | | ---- | ---- | ---- | | homeassistant_control_lights | 控制灯光 | entity_id, action, brightness, color_name, rgb_color, 等 | | homeassistant_control_climate | 控制气候设备 | entity_id, temperature, hvac_mode, preset_mode, 等 | | homeassistant_control_media_player | 控制媒体播放器 | entity_id, action, media_content_id, volume_level, 等 | | homeassistant_control_covers | 控制遮阳帘 | entity_id, action, position | | homeassistant_get_devices_by_type | 按域列出设备 | domain | | homeassistant_send_notification | 发送通知 | service, title, message, target |

系统工具

| 工具名称 | 描述 | 参数 | | ---- | ---- | ---- | | homeassistant_system_info | 获取系统信息 | 无 | | homeassistant_render_template | 渲染Jinja2模板 | template | | homeassistant_list_areas | 列出所有区域 | 无 | | homeassistant_list_devices | 列出所有设备 | 无 | | homeassistant_list_integrations | 列出集成 | 无 | | homeassistant_restart_service | 重启Home Assistant | confirm | | homeassistant_supervisor_info | 获取管理器信息 | 无 | | homeassistant_list_addons | 列出插件 | 无 | | homeassistant_search_entities | 搜索实体 | search, domain |

💻 使用示例

基础用法

// 获取灯光状态
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",
});

🎮 客户端示例

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

📁 可用示例

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

🚀 快速开始示例

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

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

🔧 技术细节

项目结构

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社区用心打造 ❤️