Home Assistant MCP Plus

一个增强版的Home Assistant MCP服务器，为 Claude Desktop 提供智能家居查询功能。

功能特性

第一期功能 ✅

• 🏠 查询房间信息 - 获取所有房间/区域的详细信息，包括实体和设备数量
• 🔧 查询设备类型 - 按域名统计所有设备类型和数量
• 🔗 连接测试 - 测试与Home Assistant的连接状态

2.0 版本新功能 🚀

• 🔌 WebSocket 连接 - 更快的实时数据传输
• 📊 实时状态监控 - 设备状态变化实时通知
• 🔄 自动重连机制 - 网络中断时自动恢复连接
• ⚡ 性能优化 - 减少网络延迟，提升响应速度

即将推出 🚧

• 设备状态查询和控制
• 自动化规则查询
• 历史数据分析
• 能源监控

快速开始

1. 配置 Claude Desktop

在 Claude Desktop 配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "homeassistant": {
      "command": "npx",
      "args": ["@rezti/homeassistant-mcp-plus"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your-long-lived-access-token"
      }
    }
  }
}

2. 获取 Home Assistant 长期访问令牌

1. 登录到Home Assistant Web界面
2. 点击左下角的用户头像
3. 滚动到底部找到"长期访问令牌"部分
4. 点击"创建令牌"
5. 输入令牌名称（如"MCP Server"）
6. 复制生成的令牌

3. 重启 Claude Desktop

关闭并重新打开Claude Desktop应用程序。

使用方法

重启 Claude Desktop 后，你可以询问：

• "显示我家里有哪些房间？"
• "办公室有哪些设备？"
• "测试Home Assistant连接状态"
• "ban_gong_shi 房间有哪些设备？"

可用工具

1. get_rooms

获取所有房间/区域的详细信息。

返回信息：

• 房间总数
• 每个房间的设备数量
• 房间列表（包含 friendly_name、area_id 和 device_count）

示例输出：

{
  "total_rooms": 2,
  "rooms": [
    {
      "friendly_name": "客厅",
      "area_id": "ke_ting",
      "device_count": 5
    },
    {
      "friendly_name": "办公室",
      "area_id": "ban_gong_shi",
      "device_count": 9
    }
  ]
}

2. get_devices_by_room

获取指定房间的设备明细信息。

参数：

• room_identifier (string): 房间标识符，可以是房间名称（如"办公室"）或区域ID（如"ban_gong_shi"）

返回信息：

• 房间标识符
• 设备总数
• 设备列表（包含 friendly_name、name、id 和 entities）

示例输出：

{
  "room_identifier": "办公室",
  "total_devices": 9,
  "devices": [
    {
      "friendly_name": "3D打印台灯",
      "name": "3D打印台灯",
      "id": "dad23a079925a72a2e5391b6b263cc43",
      "entities": [
        {
          "name": "light.3d_da_yin_tai_deng",
          "friendly_name": "3D打印台灯",
          "domain": "light"
        }
      ]
    },
    {
      "friendly_name": "Rezti Switch Z6 4 4 V3-03F87C",
      "name": "Rezti Switch Z6 4 4 V3-03F87C",
      "id": "37a4219cb56b13f01b240e0786a8cb73",
      "entities": [
        {
          "name": "switch.relay1",
          "friendly_name": "Relay 1",
          "domain": "switch"
        },
        {
          "name": "switch.relay2",
          "friendly_name": "Relay 2",
          "domain": "switch"
        }
      ]
    }
  ]
}

3. update_device_friendly_name

更新指定设备的友好名称。

参数：

• device_id (string): 设备的唯一标识符
• friendly_name (string): 要设置的新友好名称

返回信息：

• 操作是否成功
• 消息说明
• 设备ID和新名称（成功时）

示例输出：

{
  "success": true,
  "message": "设备名称更新成功",
  "device_id": "dad23a079925a72a2e5391b6b263cc43",
  "friendly_name": "新的设备名称"
}

错误示例：

{
  "success": false,
  "message": "设备未找到: invalid_device_id"
}

4. test_ha_connection

测试与Home Assistant的连接。

返回信息：

• 连接状态
• Home Assistant版本
• 配置信息

高级配置

多个 Home Assistant 实例

{
  "mcpServers": {
    "homeassistant-home": {
      "command": "npx",
      "args": ["@rezti/homeassistant-mcp-plus"],
      "env": {
        "HA_URL": "http://home.local:8123",
        "HA_TOKEN": "home-token"
      }
    },
    "homeassistant-office": {
      "command": "npx",
      "args": ["@rezti/homeassistant-mcp-plus"],
      "env": {
        "HA_URL": "http://office.local:8123",
        "HA_TOKEN": "office-token"
      }
    }
  }
}

开发和测试

本地开发

# 克隆项目
git clone https://github.com/ReZ-TI/mcp-homeassistant-plus
cd mcp-homeassistant-plus

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式运行
npm run dev

命令行测试

# 设置环境变量
export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-long-lived-access-token"

# 运行服务器
npm start

项目结构

homeassistant-mcp-plus/
├── src/
│   ├── index.ts              # MCP服务器主文件
│   └── homeassistant-ws.ts   # Home Assistant WebSocket客户端
├── build/                    # 编译输出目录
├── package.json
├── tsconfig.json
├── README.md
├── QUICK_START.md            # 详细安装指南
├── DEVELOPER.md              # 开发者文档
├── start.sh                  # 启动脚本
└── test-simple.js            # 简单测试脚本

开发脚本

• npm run build - 构建项目
• npm run watch - 监听文件变化并自动构建
• npm run dev - 开发模式运行
• npm start - 运行构建后的服务器

故障排除

连接问题

• 确保Home Assistant URL正确且可访问
• 验证长期访问令牌有效
• 检查网络连接和防火墙设置

工具调用失败

• 查看Claude Desktop启动时的日志信息
• 使用 test_ha_connection 工具验证连接
• 确保Home Assistant实例正常运行

配置问题

• 确认 Claude Desktop 配置文件路径正确
• 验证环境变量设置正确
• 检查网络连接

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

详细的安装和使用说明请参考 QUICK_START.md
开发者文档请参考 DEVELOPER.md