HomeAssistant MCP 服务器

这是一个基于 Model Context Protocol (MCP) 的 HomeAssistant 服务器，允许通过 MCP 协议与 HomeAssistant 智能家居系统进行交互。

功能特性

• 🔍 获取所有实体列表
• 📊 获取特定实体状态
• 💡 控制灯光（打开/关闭/设置亮度）
• 🔄 切换开关状态
• 🛠️ 调用任意 HomeAssistant 服务
• 📋 获取可用服务列表
• 🔗 检查连接状态
• 💬 智能提示词生成
• ⚙️ 自动化管理（创建、删除、启用/禁用）
• 📋 全局系统提示词生成

安装和配置

1. 安装依赖

cd HomeAssistant_MCP
npm install

2. 配置环境变量

创建 .env 文件或在系统环境变量中设置：

HA_BASE_URL=http://your-homeassistant-ip:8123
HA_ACCESS_TOKEN=your_long_lived_access_token

获取访问令牌：

1. 登录 HomeAssistant
2. 点击用户资料 → 创建令牌
3. 复制生成的令牌

3. 构建项目

npm run build

使用方法

开发模式运行

npm run dev

生产模式运行

npm run build
npm start

可用工具

get_entities

获取实体列表（支持分页、过滤和搜索）。

参数：

• page (number, 可选): 页码（从1开始），默认：1
• page_size (number, 可选): 每页实体数量，默认：20，最大：50
• domain (string, 可选): 过滤特定域，例如：light, switch, sensor
• search (string, 可选): 搜索实体名称中的关键词

响应示例：

{
  "total_entities": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8,
  "entities": [
    {
      "entity_id": "light.living_room",
      "state": "on",
      "friendly_name": "客厅灯",
      "domain": "light",
      "last_updated": "2024-01-01T12:00:00.000Z"
    }
  ],
  "domain_statistics": {
    "light": 25,
    "switch": 18,
    "sensor": 107
  },
  "filters": {
    "domain": "light",
    "search": "living"
  }
}

get_entity_state

获取特定实体的详细信息。

参数：

• entity_id (string): 实体ID，例如 light.living_room

turn_on_light

打开灯光。

参数：

• entity_id (string): 灯光实体ID
• brightness (number, 可选): 亮度值 (0-255)

turn_off_light

关闭灯光。

参数：

• entity_id (string): 灯光实体ID

set_light_brightness

设置灯光亮度。

参数：

• entity_id (string): 灯光实体ID
• brightness (number): 亮度值 (0-255)

toggle_switch

切换开关状态。

参数：

• entity_id (string): 开关实体ID

get_services

获取所有可用服务列表。

call_service

调用任意 HomeAssistant 服务。

参数：

• domain (string): 服务域，例如 light
• service (string): 服务名称，例如 turn_on
• service_data (object, 可选): 服务数据

check_connection

检查与 HomeAssistant 的连接状态。

generate_prompt

根据实体状态生成智能家居控制提示词。

参数：

• context (string): 用户意图或场景描述
• style (string, 可选): 提示词风格，可选值：natural（自然语言）、technical（技术版）、concise（简洁版）

示例用法：

{
  "tool": "generate_prompt",
  "arguments": {
    "context": "晚上准备睡觉",
    "style": "natural"
  }
}

响应示例：

基于当前智能家居状态，以下是针对"晚上准备睡觉"的提示词：

当前设备状态：
💡 灯光：
  - 客厅灯: 开启 (亮度: 80%)
  - 卧室灯: 关闭
🔌 开关：
  - 电视开关: 开启
📊 传感器：
  - 温度传感器: 22°C
  - 湿度传感器: 45%

建议操作：
• 关闭不必要的灯光
• 调暗卧室灯光
• 检查门窗传感器状态

改进功能

解决上下文窗口溢出问题

针对大量实体导致上下文窗口溢出的问题，我们实施了以下改进：

1. 分页机制：支持按页获取实体，避免一次性加载所有数据
2. 域过滤：可以按实体域（如 light、switch、sensor）进行过滤
3. 搜索功能：支持按关键词搜索实体名称或友好名称
4. 响应精简：返回简化的实体信息，减少数据量
5. 统计信息：提供域统计和分页信息

示例用法

获取所有实体（分页）

{
  "tool": "get_entities",
  "arguments": {
    "page": 1,
    "page_size": 20
  }
}

过滤灯光实体

{
  "tool": "get_entities",
  "arguments": {
    "domain": "light",
    "page_size": 10
  }
}

搜索实体

{
  "tool": "get_entities",
  "arguments": {
    "search": "living",
    "page_size": 5
  }
}

组合过滤和搜索

{
  "tool": "get_entities",
  "arguments": {
    "domain": "sensor",
    "search": "temperature",
    "page": 1,
    "page_size": 8
  }
}

获取特定灯光状态

{
  "tool": "get_entity_state",
  "arguments": {
    "entity_id": "light.living_room"
  }
}

打开灯光

{
  "tool": "turn_on_light",
  "arguments": {
    "entity_id": "light.living_room",
    "brightness": 200
  }
}

调用服务

{
  "tool": "call_service",
  "arguments": {
    "domain": "light",
    "service": "turn_on",
    "service_data": {
      "entity_id": "light.living_room",
      "brightness": 150
    }
  }
}

生成智能提示词

{
  "tool": "generate_prompt",
  "arguments": {
    "context": "节能模式",
    "style": "technical"
  }
}

{
  "tool": "generate_prompt",
  "arguments": {
    "context": "回家场景",
    "style": "concise"
  }
}

自动化功能

get_automations

获取所有自动化列表。

参数： 无

响应示例：

{
  "total_automations": 5,
  "automations": {
    "automation.0": {
      "alias": "晚上自动关灯",
      "description": "晚上10点自动关闭所有灯光",
      "trigger_count": 1,
      "condition_count": 0,
      "action_count": 1,
      "mode": "single",
      "enabled": true
    },
    "automation.1": {
      "alias": "温度过高开空调",
      "description": "当温度超过28度时自动打开空调",
      "trigger_count": 1,
      "condition_count": 1,
      "action_count": 1,
      "mode": "single",
      "enabled": true
    }
  }
}

create_automation

创建新的自动化。

参数：

• alias (string): 自动化名称
• description (string, 可选): 自动化描述
• trigger (array): 触发器配置
  • platform (string): 触发器平台，如：time, state, numeric_state等
  • at (string, 可选): 定时触发时间（HH:MM:SS格式）
  • entity_id (string, 可选): 实体ID，用于状态触发
  • from (string, 可选): 状态从什么值变化
  • to (string, 可选): 状态变化到什么值
• condition (array, 可选): 条件配置
  • condition (string): 条件类型，如：state, numeric_state等
  • entity_id (string): 实体ID
  • state (string, 可选): 期望的状态值
  • above (number, 可选): 数值条件：大于
  • below (number, 可选): 数值条件：小于
• action (array): 动作配置
  • service (string): 要调用的服务，如：light.turn_on
  • entity_id (string): 目标实体ID
  • brightness (number, 可选): 灯光亮度（0-255）
  • data (object, 可选): 其他服务数据
• mode (string, 可选): 自动化模式，如：single, restart, queued, parallel
• enabled (boolean, 可选): 是否启用自动化

示例用法：

定时自动化（晚上10点关灯）：

{
  "tool": "create_automation",
  "arguments": {
    "alias": "晚上自动关灯",
    "description": "晚上10点自动关闭所有灯光",
    "trigger": [
      {
        "platform": "time",
        "at": "22:00:00"
      }
    ],
    "action": [
      {
        "service": "light.turn_off",
        "entity_id": "light.living_room"
      },
      {
        "service": "light.turn_off",
        "entity_id": "light.bedroom"
      }
    ],
    "mode": "single",
    "enabled": true
  }
}

条件自动化（温度过高开空调）：

{
  "tool": "create_automation",
  "arguments": {
    "alias": "温度过高开空调",
    "description": "当温度超过28度时自动打开空调",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "sensor.temperature",
        "to": "on"
      }
    ],
    "condition": [
      {
        "condition": "numeric_state",
        "entity_id": "sensor.temperature",
        "above": 28
      }
    ],
    "action": [
      {
        "service": "climate.turn_on",
        "entity_id": "climate.air_conditioner"
      }
    ],
    "mode": "single",
    "enabled": true
  }
}

状态变化自动化（有人回家开灯）：

{
  "tool": "create_automation",
  "arguments": {
    "alias": "有人回家开灯",
    "description": "当门传感器检测到有人回家时自动开灯",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "binary_sensor.front_door",
        "from": "off",
        "to": "on"
      }
    ],
    "action": [
      {
        "service": "light.turn_on",
        "entity_id": "light.entrance",
        "brightness": 150
      }
    ],
    "mode": "single",
    "enabled": true
  }
}

delete_automation

删除自动化。

参数：

• automation_id (string): 自动化ID

示例用法：

{
  "tool": "delete_automation",
  "arguments": {
    "automation_id": "automation.0"
  }
}

toggle_automation

启用或禁用自动化。

参数：

• automation_id (string): 自动化ID
• enabled (boolean): 是否启用

示例用法：

{
  "tool": "toggle_automation",
  "arguments": {
    "automation_id": "automation.0",
    "enabled": false
  }
}

故障排除

1. 连接失败

   • 检查 HA_BASE_URL 是否正确
   • 验证 HA_ACCESS_TOKEN 是否有效
   • 确保 HomeAssistant 实例正在运行

2. 权限问题

   • 确保访问令牌具有足够的权限
   • 检查实体是否可访问

3. 网络问题

   • 确保可以访问 HomeAssistant 实例
   • 检查防火墙设置

4. 自动化创建失败

   • 检查触发器、条件、动作的配置格式
   • 确保引用的实体存在且可访问
   • 验证服务调用参数是否正确

许可证

MIT