JinDaGe - hass-mcp MCP Details

article

README

🚀 家庭助理MCP服务器

这是一个MCP服务器，它将Home Assistant的功能开放给AI助手。该服务器使用Go语言构建，允许像Claude、Cursor或OpenAI这样的AI客户端通过模型上下文协议与你的智能家居进行交互。

✨ 主要特性

实体管理：查询、搜索和控制Home Assistant实体。
服务调用：通过AI执行任何Home Assistant服务。
系统洞察：获取系统概述、领域摘要和实体历史记录。
故障排除：访问错误日志和自动化状态。
灵活传输：支持标准输入输出（本地）和HTTP（远程）模式。
生产就绪：包括OAuth支持、JWT验证、Dockerfile和Helm图表。

🛠️ 可用工具

| 工具 | 描述 | | ---- | ---- | | get_version | 获取Home Assistant版本 | | get_entity | 获取特定实体的状态（可选择过滤） | | entity_action | 打开、关闭或切换实体状态（可带参数） | | list_entities | 列出实体，可选择领域或搜索过滤 | | search_entities | 按名称、ID或属性搜索实体 | | domain_summary | 获取某个领域的统计信息和状态分布 | | system_overview | 获取Home Assistant系统的完整概述 | | list_automations | 列出所有自动化及其状态 | | call_service | 调用任何Home Assistant服务（底层API） | | get_history | 获取实体的状态变更历史 | | get_error_log | 获取Home Assistant错误日志 | | restart_ha | 重启Home Assistant |

🚀 快速开始

要求

Go 1.24或更高版本（仅从源代码构建时需要）
具有API访问权限的Home Assistant实例
Home Assistant的长期访问令牌

获取Home Assistant令牌

访问你的Home Assistant实例。
点击左下角的个人资料。
滚动到“长期访问令牌”。
创建一个新令牌并复制它。

安装

从源代码构建

git clone https://github.com/achetronic/hass-mcp.git
cd hass-mcp
make build

二进制文件将在bin/hass-mcp-{os}-{arch}生成。

Docker

docker pull ghcr.io/achetronic/hass-mcp:latest

或者本地构建：

make docker-build IMG=your-registry/hass-mcp:latest

⚙️ 配置

根据docs/中的示例创建配置文件：

标准输入输出模式（本地客户端）

server:
  name: "Home Assistant MCP"
  version: "0.1.0"
  transport:
    type: "stdio"

home_assistant:
  url: "${HA_URL}" # 例如，http://homeassistant.local:8123
  token: "${HA_TOKEN}" # 长期访问令牌

HTTP模式（远程客户端）

基本HTTP服务器（私有网络）

对于内部使用或开发，你可以运行一个无需身份验证的简单HTTP服务器：

server:
  name: "Home Assistant MCP"
  version: "0.1.0"
  transport:
    type: "http"
    http:
      host: ":8080"

home_assistant:
  url: "${HA_URL}"
  token: "${HA_TOKEN}"

带有OAuth 2.1的HTTP服务器（公开暴露）

对于面向公众的部署，服务器支持带有JWT验证的OAuth 2.1。这允许通过将身份验证委托给身份提供者（如Keycloak、Auth0、Okta等），从远程AI客户端（如Claude Web或ChatGPT）进行安全访问。服务器实现了：

RFC 8414：OAuth授权服务器元数据 (/.well-known/oauth-authorization-server)
RFC 9728：OAuth受保护资源元数据 (/.well-known/oauth-protected-resource)

server:
  name: "Home Assistant MCP"
  version: "0.1.0"
  transport:
    type: "http"
    http:
      host: ":8080"

home_assistant:
  url: "${HA_URL}"
  token: "${HA_TOKEN}"

middleware:
  jwt:
    enabled: true
    validation:
      strategy: "local" # 使用JWKS在内部验证JWT
      local:
        jwks_uri: "https://keycloak.example.com/realms/mcp-servers/protocol/openid-connect/certs"
        cache_interval: "10s"
        # 可选：用于验证JWT声明的CEL表达式
        allow_conditions:
          - expression: 'payload.groups.exists(g, g == "home-assistant-users")'

oauth_authorization_server:
  enabled: true
  issuer_uri: "https://keycloak.example.com/realms/mcp-servers"

oauth_protected_resource:
  enabled: true
  resource: "https://hass-mcp.example.com/mcp"
  auth_servers:
    - "https://keycloak.example.com/realms/mcp-servers"
  scopes_supported:
    - openid
    - profile

⚠️ 重要提示：如果你有一个上游代理（如Istio）来验证JWT，你可以使用strategy: "external"并配置forwarded_header以从代理接收验证后的JWT。

💡 使用建议：支持使用${VAR}语法的环境变量。

完整的配置示例请参阅docs/config-http.yaml。

💻 使用示例

本地客户端（Claude Desktop、Cursor、VS Code）

对于本地AI客户端，使用标准输入输出传输。添加到你的客户端配置中： Claude Desktop (claude_desktop_config.json)：

{
  "mcpServers": {
    "home-assistant": {
      "command": "/path/to/hass-mcp",
      "args": ["--config", "/path/to/config-stdio.yaml"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your-token-here"
      }
    }
  }
}

Cursor (.cursor/mcp.json)：

{
  "mcpServers": {
    "home-assistant": {
      "command": "/path/to/hass-mcp",
      "args": ["--config", "/path/to/config-stdio.yaml"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your-token-here"
      }
    }
  }
}

远程客户端（Claude Web、OpenAI）

对于远程客户端，使用HTTP传输：

export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-token-here"
./hass-mcp --config config-http.yaml

服务器默认在8080端口启动。可用的端点取决于你的配置： | 端点 | 描述 | 启用条件 | | ---- | ---- | ---- | | /mcp | MCP协议端点 | 始终 | | /.well-known/oauth-authorization-server | OAuth元数据（RFC 8414） | oauth_authorization_server.enabled: true | | /.well-known/oauth-protected-resource | 受保护资源元数据（RFC 9728） | oauth_protected_resource.enabled: true |

💻 开发

# 运行服务器
make run

# 格式化代码
make fmt

# 运行代码检查
make lint

# 运行代码检查并自动修复
make lint-fix

# 构建二进制文件
make build

# 显示所有可用目标
make help

🚢部署

Kubernetes

在chart/目录中提供了一个Helm图表：

# 更新依赖
helm dependency update ./chart

# 安装
helm install hass-mcp ./chart \
  --set config.home_assistant.url="http://homeassistant.local:8123" \
  --set config.home_assistant.token="your-token-here"

在chart/values.yaml中配置值以匹配你的环境。

生产建议

身份验证：在生产环境中使用反向代理（如Istio、Traefik）进行JWT验证。
OAuth：启用OAuth端点以进行远程客户端身份验证。
会话亲和性：在运行多个副本时，使用一致哈希路由器实现会话亲和性。
密钥管理：将令牌存储在Kubernetes密钥或外部密钥管理器中。

📁 项目结构

├── cmd/main.go              # 应用程序入口点
├── api/                     # 配置类型
├── internal/
│   ├── hass/                # Home Assistant API客户端
│   ├── tools/               # MCP工具实现
│   ├── handlers/            # HTTP端点处理程序
│   ├── middlewares/         # HTTP/JWT中间件
│   ├── config/              # 配置加载
│   └── globals/             # 应用程序上下文
├── docs/                    # 示例配置
└── chart/                   # Kubernetes的Helm图表

🔍 工作原理

flowchart LR
    A[AI助手<br/>Claude、Cursor等] <-->|MCP协议<br/>标准输入输出或HTTP/SSE| B[hass-mcp<br/>服务器]
    B <-->|REST API| C[Home Assistant<br/>实例]

AI助手通过MCP（本地客户端使用标准输入输出，远程客户端使用HTTP/SSE）连接到hass-mcp。
助手可以发现可用工具并调用它们。
hass-mcp将工具调用转换为Home Assistant REST API请求。
结果以结构化格式返回给助手。

🔗 相关链接

🤝 贡献

欢迎贡献代码。请在提交拉取请求之前先开一个问题讨论更改。

📄 许可证

本项目采用Apache 2.0许可证。详情请参阅LICENSE。

hass-mcp