Skip to main content
Glama
enesjakozh
tevonsb

homeassistant-mcp

by tevonsb
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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

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

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

执照Node.jsDocker Compose新公共管理TypeScript测试覆盖率

特征

  • 🎮设备控制：通过自然语言控制任何家庭助理设备

  • 🔄实时更新：通过服务器发送事件（SSE）获取即时更新

  • 🤖自动化管理：创建、更新和管理自动化

  • 📊状态监控：跟踪和查询设备状态

  • 🔐安全：基于令牌的身份验证和速率限制

  • 📱移动就绪：可与任何支持 HTTP 的客户端配合使用

Related MCP server: Home Assistant MCP

使用 SSE 进行实时更新

该服务器包含一个强大的服务器发送事件 (SSE) 系统，可从您的 Home Assistant 实例提供实时更新。这允许您：

  • 🔄 获取任何设备的即时状态变化

  • 📡 监控自动化触发器和执行

  • 🎯 订阅特定域或实体

  • 📊 跟踪服务调用和脚本执行

快速 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 系统的完整文档，请参阅SSE_API.md 。

目录

主要特点

核心功能🎮

  • 智能设备控制

    • 💡灯光：亮度、色温、RGB 颜色

    • 🌡️气候：温度、暖通空调模式、风扇模式、湿度

    • 🚪封面：位置和倾斜控制

    • 🔌开关：开/关控制

    • 🚨传感器和接触器：状态监控

    • 🎵媒体播放器：播放控制、音量、源选择

    • 🌪️风扇：速度、摆动、方向

    • 🔒锁：锁定/解锁控制

    • 🧹吸尘器：启动、停止、返回基座

    • 📹相机：运动检测、快照

系统管理🛠️

  • 附加组件管理

    • 浏览可用的附加组件

    • 安装/卸载附加组件

    • 启动/停止/重启附加组件

    • 版本管理

    • 配置访问

  • 包裹管理（HACS）

    • 与 Home Assistant Community Store 集成

    • 多种封装类型支持：

      • 自定义集成

      • 前端主题

      • Python 脚本

      • AppDaemon 应用程序

      • NetDaemon 应用程序

    • 版本控制和更新

    • 存储库管理

  • 自动化管理

    • 创建和编辑自动化

    • 高级配置选项：

      • 多种触发类型

      • 复杂条件

      • 动作序列

      • 执行模式

    • 复制并修改现有的自动化

    • 启用/禁用自动化规则

    • 手动触发自动化

架构特点🏗️

  • 智能组织

    • 基于区域和楼层的设备分组

    • 状态监控与查询

    • 智能情境感知

    • 历史数据访问

  • 稳健的架构

    • 全面的错误处理

    • 状态验证

    • 安全 API 集成

    • TypeScript 类型安全

    • 广泛的测试覆盖范围

先决条件

  • Node.js 20.10.0 或更高版本

  • NPM包管理器

  • Docker Compose用于容器化

  • 运行Home Assistant实例

  • Home Assistant 长期访问令牌（如何获取令牌）

  • 安装HACS以实现包裹管理功能

  • 附加组件管理的主管访问权限

安装

基本设置

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

# Install dependencies
npm install

# Build the project
npm run build

Docker 设置（推荐）

该项目包括 Docker 支持，以便在不同平台之间轻松部署和保持一致的环境。

  1. 克隆存储库：

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

  2. 配置环境：

    cp .env.example .env

    使用您的 Home Assistant 配置编辑.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 设置包括：

  • 多阶段构建以获得最佳图像尺寸

  • 容器监控的健康检查

  • 用于环境配置的卷安装

  • 失败时自动重启容器

  • 暴露 3000 端口用于 API 访问

Docker Compose 环境变量

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

  • HASS_HOST ：您的 Home Assistant 实例 URL

  • HASS_TOKEN ：Home Assistant 的长期访问令牌

  • HASS_SOCKET_URL ：家庭助理的 WebSocket URL

  • PORT ：服务器端口（默认值：3000）

  • NODE_ENV ：环境（生产/开发）

  • DEBUG ：启用调试模式（true/false）

配置

环境变量

# 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（或其他客户端）

要使用新的 Home Assistant 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 个请求

  • 每个 IP 每分钟 1000 个 WebSocket 连接请求

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

{
  "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 版本（

    • **解决方案：**更新至 Node.js 20.10.0+ GXP38

  2. 连接问题

    • 验证 Home Assistant 是否正在运行

    • 检查HASS_HOST可访问性

    • 验证令牌权限

    • 确保 WebSocket 连接以实现实时更新

  3. 附加组件管理问题

    • 验证主管访问权限

    • 检查附加组件兼容性

    • 验证系统资源

  4. HACS集成问题

    • 验证 HACS 安装

    • 检查 HACS 集成状态

    • 验证存储库访问权限

  5. 自动化问题

    • 验证实体可用性

    • 检查触发条件

    • 验证服务调用

    • 监控执行日志

项目状态

✅完成

  • 实体、楼层和区域访问

  • 设备控制（灯光、气候、盖子、开关、触点）

  • 附加组件管理系统

  • 通过 HACS 进行包裹管理

  • 高级自动化配置

  • 基本状态管理

  • 错误处理和验证

  • Docker 容器化

  • Jest 测试设置

  • TypeScript 集成

  • 环境变量管理

  • 家庭助理 API 集成

  • 项目文档

🚧进行中

  • 用于实时更新的 WebSocket 实现

  • 增强的安全功能

  • 刀具组织优化

  • 性能优化

  • 资源上下文整合

  • API文档生成

  • 多平台桌面集成

  • 高级错误恢复

  • 自定义提示测试

  • 增强的 macOS 集成

  • 类型安全改进

  • 测试覆盖范围扩展

贡献

  1. 分叉存储库

  2. 创建功能分支

  3. 实施您的更改

  4. 添加新功能测试

  5. 确保所有测试通过

  6. 提交拉取请求

资源

执照

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tevonsb/homeassistant-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server