hass MCP (Achetronic)

一个MCP服务器，向AI助手公开家庭助理功能。内置Go，它使Claude、Cursor或OpenAI等AI客户端能够通过 模型上下文协议.

特性

• 实体管理：查询、搜索和控制家庭助理实体
• 服务调用：通过AI执行任何家庭助理服务
• 系统洞察：获取概述、域摘要和实体历史记录
• 故障排除：访问错误日志和自动化状态
• 柔性运输：支持stdio（本地）和HTTP（远程）模式
• 生产就绪：包括OAuth支持、JWT验证、Dockerfile和Helm chart

可用工具

快速开始

需求

• 转到1.24或更高版本（仅适用于从源代码构建）
• 具有API访问权限的Home Assistant实例
• 来自Home Assistant的长期访问令牌

获取家庭助理令牌

1. 导航到您的家庭助理实例
2. 点击您的个人资料（左下角）
3. 滚动到“长期访问令牌”
4. 创建新令牌并复制它

安装

从源代码构建

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

二进制文件将在以下时间创建 bin/hass-mcp-{os}-{arch}.

码头工人

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}" # e.g., http://homeassistant.local:8123
  token: "${HA_TOKEN}" # Long-lived access 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服务器（公开）

对于面向公众的部署，服务器支持 OAuth 2.1 通过JWT验证。这可以通过将身份验证委托给身份提供者（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" # Validate JWTs internally using JWKS
      local:
        jwks_uri: "https://keycloak.example.com/realms/mcp-servers/protocol/openid-connect/certs"
        cache_interval: "10s"
        # Optional: CEL expressions to validate JWT claims
        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

小贴士：如果你有一个验证JWT的上游代理（例如Istio），你可以使用 strategy: "external" 并配置 forwarded_header 以从代理接收经过验证的JWT。

备注：环境变量支持使用 ${VAR} 语法。

看 docs/config-http.yaml 以获得完整的配置示例。

用法

本地客户端（克劳德桌面、光标、VS代码）

对于本地AI客户端，请使用stdio传输。添加到您的客户端配置中：

克劳德桌面版 (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/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上启动。可用端点取决于您的配置：

发展

# Run the server
make run

# Format code
make fmt

# Run linter
make lint

# Run linter with auto-fix
make lint-fix

# Build binary
make build

# Show all available targets
make help

部署

Kubernetes

Helm图表在 chart/ 目录：

# Update dependencies
helm dependency update ./chart

# Install
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 secrets或外部秘密管理器中

项目结构

├── cmd/main.go              # Application entry point
├── api/                     # Configuration types
├── internal/
│   ├── hass/                # Home Assistant API client
│   ├── tools/               # MCP tool implementations
│   ├── handlers/            # HTTP endpoint handlers
│   ├── middlewares/         # HTTP/JWT middlewares
│   ├── config/              # Configuration loading
│   └── globals/             # Application context
├── docs/                    # Example configurations
└── chart/                   # Helm chart for Kubernetes

运作原理

flowchart LR
    A[AI Assistant
Claude, Cursor, etc.] |MCP Protocol
stdio or HTTP/SSE| B[hass-mcp
Server]
    B |REST API| C[Home Assistant
Instance]

1. AI助手通过mcp连接到hass-mcp（本地客户端为stdio，远程客户端为HTTP/SSE）
2. 助手可以发现可用的工具并调用它们
3. hass-mcp将工具调用转换为Home Assistant REST API请求
4. 结果以结构化格式返回给助手

相关链接

• 模型上下文协议规范
• 家庭助手REST API
• mcp-go图书馆

贡献

欢迎捐款。请在提交pull请求之前打开一个问题来讨论更改。

许可证

此项目根据Apache 2.0许可证获得许可。看 许可证 了解详情。