homeassistant-mcp

🚀 家庭助理 Home Assistant 说明文档

本说明文档详细介绍了家庭助理 Home Assistant 的配置、使用、集成等多方面内容，帮助你更好地使用该服务。

🚀 快速开始

在开始使用 Home Assistant 前，你需要进行相应的配置，下面将详细介绍配置步骤。

📦 安装指南

MCP 服务器配置

配置文件示例

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "HASS_TOKEN": "your_home_assistant_token_here",
        "HASS_HOST": "http://your_home_assistant_host:8123"
      }
    }
  }
}

环境变量

• HASS_TOKEN：Home Assistant 的访问令牌。
• HASS_HOST：Home Assistant 服务的 URL，格式为 http://IP:端口。

启动脚本

方案一：使用 Node.js 直接运行

node index.js

方案二：使用 npm 脚包

1. 安装 MCP 服务器：

npm install homeassistant-mcp

2. 启动服务器：

npx homeassistant-mcp

使用 Home Assistant 的启动脚本

将以下内容添加到 homeassistant.conf 文件中：

[HomeAssistantMCP]
command=node
args=index.js
environment=HASS_TOKEN="your_token_here",HASS_HOST="http://IP:port"

然后重启 Home Assistant 服务。

💻 使用示例

标准输入输出模式（_stdio）

启用标准输入输出模式

在 .env 文件中添加：

USE_STDIO_TRANSPORT=true

运行脚本

方案一：使用 Node.js 直接运行

node index.js --stdio

方案二：使用 npm 脚包

npx homeassistant-mcp --stdio

选项参数

• --debug：启用调试模式。
• --rebuild：强制重新构建项目。
• --help：显示帮助信息。

标准输入输出消息格式

请求格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tool-name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

响应格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // 工具特定的结果数据
  }
}

错误响应格式

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32700,
    "message": "错误信息",
    "data": {} // 可选的错误细节
  }
}

通知格式（服务器到客户端）

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // 通知数据
  }
}

支持的错误代码

| 码 | 描述 | 含义 | | ---- | ---- | ---- | | -32700 | 解析错误 | 接收到无效的 JSON | | -32600 | 请求无效 | JSON 不是一个有效的请求对象 | | -32601 | 方法未找到 | 方法不存在或不可用 | | -32602 | 参数无效 | 方法参数无效 | | -32603 | 内部错误 | 内部 JSON - RPC 错误 | | -32000 | 工具执行 | 执行工具时出错 | | -32001 | 验证错误 | 参数验证失败 |

与 Claude Desktop 集成

配置步骤

修改配置文件

找到或创建以下路径的配置文件：

• macOS：

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

• Linux：

nano ~/.config/Claude/claude_desktop_config.json

• Windows：

notepad %APPDATA%\Claude\claude_desktop_config.json

添加 MCP 服务器配置

在文件中添加或修改以下内容：

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "HASS_TOKEN": "your_token_here",
        "HASS_HOST": "http://IP:port"
      }
    }
  }
}

重启服务

保存配置文件后，重启 Claude Desktop 服务。

示例用法

启动 MCP 服务器

npx homeassistant-mcp --stdio

发送请求示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getWeather",
  "params": {
    "location": "北京"
  }
}

接收响应示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "temperature": 25,
    "condition": "晴朗"
  }
}

📚 详细文档

错误处理

常见错误及解决方案

• 错误代码 -32700：请求的 JSON 格式无效。请检查请求数据是否符合 JSON 标准。
• 错误代码 -32601：方法未找到。请确认调用的方法名称正确且已注册。
• 错误代码 -32000：工具执行失败。请检查环境变量和依赖项是否配置正确。

高级功能

日志记录

启用调试模式以获取详细日志：

npx homeassistant-mcp --debug stdio

日志文件通常位于项目目录的 logs 文件夹中，具体位置取决于项目的配置。

性能调优

• 内存优化：使用 --max-old-space-size 参数限制 V8 引擎的最大内存占用。

node --max-old-space-size=512 index.js --stdio

• 网络性能：配置代理服务器或调整 HTTP 请求超时设置。

安全注意事项

• 访问控制：确保 MCP 服务器仅允许来自受信任来源的连接。
• 令牌安全：存储和传输 HASS_TOKEN 时，请确保使用安全协议（如 HTTPS）以防止未授权访问。
• 日志监控：定期审查日志文件，发现并处理潜在的安全事件。

更新日志

版本 1.0.0 (2023 - 10 - 05)

• 新增标准输入输出模式支持。
• 优化错误处理机制。
• 改进与 Claude Desktop 的集成体验。

版本 0.9.0 (2023 - 08 - 10)

• 初始版本发布，提供基础功能。

联系方式

如需反馈或技术支持，请访问 官方文档 或联系支持团队。