Hass MCP

🚀 家庭助理MCP服務器

這是一個MCP服務器，它將Home Assistant的功能開放給AI助手。該服務器使用Go語言構建，允許像Claude、Cursor或OpenAI這樣的AI客戶端通過模型上下文協議與你的智能家居進行交互。

✨ 主要特性

• 實體管理：查詢、搜索和控制Home Assistant實體。
• 服務調用：通過AI執行任何Home Assistant服務。
• 系統洞察：獲取系統概述、領域摘要和實體歷史記錄。
• 故障排除：訪問錯誤日誌和自動化狀態。
• 靈活傳輸：支持標準輸入輸出（本地）和HTTP（遠程）模式。
• 生產就緒：包括OAuth支持、JWT驗證、Dockerfile和Helm圖表。

🛠️ 可用工具

🚀 快速開始

要求

• Go 1.24或更高版本（僅從源代碼構建時需要）
• 具有API訪問權限的Home Assistant實例
• Home Assistant的長期訪問令牌

獲取Home Assistant令牌

1. 訪問你的Home Assistant實例。
2. 點擊左下角的個人資料。
3. 滾動到“長期訪問令牌”。
4. 創建一個新令牌並複製它。

安裝

從源代碼構建

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

⚙️ 配置

根據中的示例創建配置文件：

標準輸入輸出模式（本地客戶端）

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}語法的環境變量。

完整的配置示例請參閱。

💻 使用示例

本地客戶端（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端口啟動。可用的端點取決於你的配置：

💻 開發

# 運行服務器
make run

# 格式化代碼
make fmt

# 運行代碼檢查
make lint

# 運行代碼檢查並自動修復
make lint-fix

# 構建二進制文件
make build

# 顯示所有可用目標
make help

🚢部署

Kubernetes

在目錄中提供了一個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/>實例]

1. AI助手通過MCP（本地客戶端使用標準輸入輸出，遠程客戶端使用HTTP/SSE）連接到hass-mcp。
2. 助手可以發現可用工具並調用它們。
3. hass-mcp將工具調用轉換為Home Assistant REST API請求。
4. 結果以結構化格式返回給助手。

🔗 相關鏈接

• 模型上下文協議規範
• Home Assistant REST API
• mcp-go庫

🤝 貢獻

歡迎貢獻代碼。請在提交拉取請求之前先開一個問題討論更改。

📄 許可證

本項目採用Apache 2.0許可證。詳情請參閱LICENSE。