AI导哈

智能家居控制服务器

一个连接Home Assistant和语言学习模型（LLM）的服务器，通过自然语言实现对智能家居设备的控制和管理。

  • by tevonsb
  • TypeScript
  • 本地部署
  • 576 星标
  • 更新于
在 GitHub 查看 tevonsb/homeassistant-mcp

使用说明

家庭助理的模型上下文协议服务器

服务器使用MCP协议与LLM应用程序共享对本地Home Assistant实例的访问。

家庭助理实例和语言学习模型（LLM）之间的强大桥梁，通过模型上下文协议（MCP）实现对智能家居设备的自然语言控制和监控。该服务器提供了一个全面的API，用于管理整个Home Assistant生态系统，从设备控制到系统管理。

特性

  • 🎮 设备控制：通过自然语言控制任何家庭助理设备
  • 🔄 实时更新：通过服务器发送事件（SSE）获取即时更新
  • 🤖 自动化管理：创建、更新和管理自动化
  • 📊 状态监测：跟踪和查询设备状态
  • 🔐 安全：基于令牌的身份验证和速率限制
  • 📱 移动就绪：适用于任何支持HTTP的客户端

SSE实时更新

该服务器包括一个功能强大的服务器发送事件（SSE）系统，可从您的家庭助理实例提供实时更新。这使您能够：

  • 🔄 获取任何设备的即时状态更改
  • 📡 监控自动化触发器和执行
  • 🎯 订阅特定域或实体
  • 📊 跟踪服务调用和脚本执行

快速SSE示例

const eventSource = new EventSource(
  'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update received:', data);
};

看 SSE_API.md 获取SSE系统的完整文档。

目录

主要特点

核心功能🎮

  • 智能设备控制
    • 💡 光：亮度、色温、RGB颜色
    • 🌡️ 气候：温度、暖通空调模式、风扇模式、湿度
    • 🚪 封面：位置和倾斜控制
    • 🔌 开关：开/关控制
    • 🚨 传感器和触点：国家监测
    • 🎵 媒体播放器：播放控制、音量、源选择
    • 🌪️ 粉丝：速度、振荡、方向
    • 🔒 锁：锁定/解锁控制
    • 🧹 真空吸尘器：启动、停止、返回基地
    • 📹 相机：运动检测、快照

系统管理🛠️

  • 附加组件管理

    • 浏览可用的附加组件
    • 安装/卸载附加组件
    • 启动/停止/重新启动附加组件
    • 版本管理
    • 配置访问

  • 包管理（HACS）

    • 与Home Assistant社区商店集成
    • 支持多种包类型：
      • 自定义集成
      • 前端主题
      • Python脚本
      • AppDaemon应用程序
      • NetDaemon应用程序
    • 版本控制和更新
    • 存储库管理

  • 自动化管理

    • 创建和编辑自动化
    • 高级配置选项：
      • 多种触发器类型
      • 复杂条件
      • 动作序列
      • 执行模式
    • 复制和修改现有自动化
    • 启用/禁用自动化规则
    • 手动触发自动化

架构特征🏗️

  • 智慧型组织

    • 基于面积和楼层的设备分组
    • 状态监视和查询
    • 智能上下文感知
    • 历史数据访问

  • 稳健的体系结构

    • 全面的错误处理
    • 状态验证
    • 安全的API集成
    • TypeScript类型安全
    • 广泛的测试覆盖范围

先决条件

  • Node.js 20.10.0或更高
  • NPM 包管理器
  • Docker Compose 集装箱化
  • 跑步 家庭助手 例子
  • Home Assistant长期访问令牌(如何获取代币)
  • 计算机危险判定系统 已安装包管理功能
  • 主管 插件管理访问权限

安装

基本设置

# Clone the repository
git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp

# Install dependencies
npm install

# Build the project
npm run build

Docker安装程序（推荐）

该项目包括Docker支持，以实现跨不同平台的轻松部署和一致的环境。

  1. 克隆存储库：

    git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp

  2. 配置环境：

    cp .env.example .env

    编辑 .env 使用您的家庭助理配置文件：

    # Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket

# Server Configuration
PORT=3000
NODE_ENV=production
DEBUG=false

  3. 使用Docker Compose构建和运行：

    # Build and start the containers
docker compose up -d

# View logs
docker compose logs -f

# Stop the service
docker compose down

  4. 验证安装： 服务器现在应该在以下位置运行 http://localhost:3000。您可以在以下位置查看运行状况端点 http://localhost:3000/health.

  5. 更新应用程序：

    # Pull the latest changes
git pull

# Rebuild and restart the containers
docker compose up -d --build

Docker配置

Docker设置包括：

  • 多阶段构建，实现最佳图像大小
  • 集装箱监控的健康检查
  • 用于环境配置的卷装
  • 故障时自动重启容器
  • 用于API访问的暴露端口3000

Docker编写环境变量

所有环境变量都可以在 .env 文件。支持以下变量：

  • HASS_HOST：您的家庭助理实例URL
  • HASS_TOKEN：家庭助理的长期访问令牌
  • HASS_SOCKET_URL：家庭助理的WebSocket URL
  • PORT：服务器端口（默认值：3000）
  • NODE_ENV：环境（生产/开发）
  • DEBUG：启用调试模式（真/假）

配置

环境变量

# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123  # Your Home Assistant instance URL
HASS_TOKEN=your_home_assistant_token       # Long-lived access token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL

# Server Configuration
PORT=3000                # Server port (default: 3000)
NODE_ENV=production     # Environment (production/development)
DEBUG=false            # Enable debug mode

# Test Configuration
TEST_HASS_HOST=http://localhost:8123  # Test instance URL
TEST_HASS_TOKEN=test_token           # Test token

配置文件

  1. 发展：复制 .env.example 到 .env.development
  2. 生产：复制 .env.example 到 .env.production
  3. 测试：复制 .env.example 到 .env.test

添加到Claude Desktop（或其他客户端）

要使用新的家庭助理MCP服务器，您可以将Claude Desktop添加为客户端。将以下内容添加到配置中。请注意，这将在claude中运行MCP，不适用于Docker方法。

{
  "homeassistant": {
    "command": "node",
    "args": [<path/to/your/dist/folder>]
    "env": {
      NODE_ENV=development
      HASS_HOST=http://homeassistant.local:8123
      HASS_TOKEN=your_home_assistant_token
      PORT=3000
      HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
      LOG_LEVEL=debug
    }
  }
}

api参考

设备控制

通用实体控制

{
  "tool": "control",
  "command": "turn_on",  // or "turn_off", "toggle"
  "entity_id": "light.living_room"
}

灯光控制

{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 128,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}

附加组件管理

列出可用附加组件

{
  "tool": "addon",
  "action": "list"
}

安装附加组件

{
  "tool": "addon",
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}

管理附加组件状态

{
  "tool": "addon",
  "action": "start",  // or "stop", "restart"
  "slug": "core_configurator"
}

包管理

列出HACS软件包

{
  "tool": "package",
  "action": "list",
  "category": "integration"  // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}

安装程序包

{
  "tool": "package",
  "action": "install",
  "category": "integration",
  "repository": "hacs/integration",
  "version": "1.32.0"
}

自动化管理

创建自动化

{
  "tool": "automation_config",
  "action": "create",
  "config": {
    "alias": "Motion Light",
    "description": "Turn on light when motion detected",
    "mode": "single",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "binary_sensor.motion",
        "to": "on"
      }
    ],
    "action": [
      {
        "service": "light.turn_on",
        "target": {
          "entity_id": "light.living_room"
        }
      }
    ]
  }
}

复制自动化

{
  "tool": "automation_config",
  "action": "duplicate",
  "automation_id": "automation.motion_light"
}

核心功能

状态管理

GET /api/state
POST /api/state

管理系统的当前状态。

请求示例：

POST /api/state
{
  "context": "living_room",
  "state": {
    "lights": "on",
    "temperature": 22
  }
}

上下文更新

POST /api/context

用新信息更新当前上下文。

请求示例：

POST /api/context
{
  "user": "john",
  "location": "kitchen",
  "time": "morning",
  "activity": "cooking"
}

动作端点

执行操作

POST /api/action

使用给定的参数执行指定的操作。

请求示例：

POST /api/action
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}

批量操作

POST /api/actions/batch

按顺序执行多个操作。

请求示例：

POST /api/actions/batch
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}

查询功能

获取可用操作

GET /api/actions

返回所有可用操作的列表。

示例响应：

{
  "actions": [
    {
      "name": "turn_on_lights",
      "parameters": ["room", "brightness"],
      "description": "Turns on lights in specified room"
    },
    {
      "name": "set_temperature",
      "parameters": ["temperature"],
      "description": "Sets temperature in current context"
    }
  ]
}

上下文查询

GET /api/context?type=current

检索上下文信息。

示例响应：

{
  "current_context": {
    "user": "john",
    "location": "kitchen",
    "time": "morning",
    "activity": "cooking"
  }
}

WebSocket事件

服务器支持通过WebSocket连接进行实时更新。

// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};

支持的活动

  • state_change：系统状态更改时发出
  • context_update：更新上下文时触发
  • action_executed：动作完成时发出
  • error：发生错误时发出

事件数据示例：

{
  "event": "state_change",
  "data": {
    "previous_state": {
      "lights": "off"
    },
    "current_state": {
      "lights": "on"
    },
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

错误处理

所有端点都返回标准HTTP状态代码：

  • 200：成功
  • 400：错误请求
  • 401：未经授权
  • 403：禁止
  • 404：未找到
  • 500：内部服务器错误

错误响应格式：

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Missing required parameter: room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}

速率限制

API实施速率限制以防止滥用：

  • 常规端点每IP每分钟100个请求
  • WebSocket连接的每个IP每分钟1000个请求

当超过速率限制时，服务器返回：

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "reset_time": "2024-03-20T10:31:00Z"
  }
}

示例用法

使用curl

# Get current state
curl -X GET \
  http://localhost:3000/api/state \
  -H 'Authorization: ApiKey your_api_key_here'

# Execute action
curl -X POST \
  http://localhost:3000/api/action \
  -H 'Authorization: ApiKey your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "turn_on_lights",
    "parameters": {
      "room": "living_room",
      "brightness": 80
    }
  }'

使用JavaScript

// Execute action
async function executeAction() {
  const response = await fetch('http://localhost:3000/api/action', {
    method: 'POST',
    headers: {
      'Authorization': 'ApiKey your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'turn_on_lights',
      parameters: {
        room: 'living_room',
        brightness: 80
      }
    })
  });
  
  const data = await response.json();
  console.log('Action result:', data);
}

发展

# Development mode with hot reload
npm run dev

# Build project
npm run build

# Production mode
npm run start

# Run tests
npx jest --config=jest.config.cjs

# Run tests with coverage
npx jest --coverage

# Lint code
npm run lint

# Format code
npm run format

故障排除

常见问题

  1. Node.js版本(toSorted is not a function)

    • 解决方案： 更新到Node.js 20.10.0+
    nvm install 20.10.0
nvm use 20.10.0

  2. 连接问题

    • 验证家庭助理是否正在运行
    • 检查 HASS_HOST 无障碍
    • 验证令牌权限
    • 确保WebSocket连接以进行实时更新

  3. 附加管理问题

    • 验证主管访问权限
    • 检查附加组件兼容性
    • 验证系统资源

  4. HACS集成问题

    • 验证HACS安装
    • 检查HACS集成状态
    • 验证存储库访问权限

  5. 自动化问题

    • 验证实体可用性
    • 检查触发条件
    • 验证服务呼叫
    • 监控执行日志

项目状态

✅ 完成

  • 实体、楼层和区域访问权限
  • 设备控制（灯、气候、盖子、开关、触点）
  • 附加管理系统
  • 通过HACS进行包管理
  • 高级自动化配置
  • 基本状态管理
  • 错误处理和验证
  • Docker容器化
  • Jest测试设置
  • TypeScript集成
  • 环境变量管理
  • 首页助手API集成
  • 项目文档

🚧 进行中

  • 用于实时更新的WebSocket实现
  • 增强的安全功能
  • 刀具组织优化
  • 性能优化
  • 资源上下文集成
  • API文档生成
  • 多平台桌面集成
  • 高级错误恢复
  • 自定义提示测试
  • 增强的macOS集成
  • 类型安全改进
  • 测试覆盖范围扩展

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 实施您的更改
  4. 添加新功能的测试
  5. 确保所有测试通过
  6. 提交拉取请求

资源

许可证

MIT许可证-请参阅 许可证 文件

相关 MCP