AI导哈

Home Assistant连接服务

一个通过REST API与Home Assistant交互的模型上下文协议(MCP)服务器，提供健康检查、实体管理、服务调用和设备控制等功能。

  • by javiermunozalonso
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 javiermunozalonso/home-assistant-mcp

使用说明

家庭助理MCP服务器

一种模型上下文协议（MCP）服务器，通过其REST API提供与Home Assistant交互的工具。

特性

  • 健康检查：验证Home Assistant API连接
  • 实体管理：列出和查询实体状态
  • 服务调用：执行任何家庭助理服务
  • 设备控制：使用方便的方法打开/关闭、切换设备
  • 历史：检索历史状态数据
  • 事件：火灾自定义事件

需求

  • Python 3.12+
  • 启用REST API的Home Assistant实例
  • 来自Home Assistant的长期访问令牌

安装

使用紫外线（推荐）

# Clone the repository
cd ha_connection

# Install dependencies (creates virtual environment automatically)
uv sync

# Install with dev dependencies for testing
uv sync --group dev

手动安装

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

配置

  1. 复制示例环境文件：

    cp .env.example .env

  2. 编辑 .env 使用您的家庭助理详细信息：

    HA_URL=http://your-home-assistant:8123
HA_TOKEN=your_long_lived_access_token
HA_VERIFY_SSL=true
HA_TIMEOUT=30

  3. 在Home Assistant中生成长期访问令牌：

    • 转到您的个人资料（单击侧栏中的姓名）
    • 滚动到“长期访问令牌”
    • 点击“创建令牌”
    • 将令牌复制到您的 .env 文件

用法

运行MCP服务器

# Using uv
uv run home-assistant-mcp

# Or directly
uv run python -m home_assistant_mcp.server

使用Claude Desktop进行配置

添加到您的Claude Desktop配置(~/.config/claude/claude_desktop_config.json 在Linux/Mac或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "home-assistant": {
      "command": "uv",
      "args": ["--directory", "/path/to/ha_connection", "run", "home-assistant-mcp"],
      "env": {
        "HA_URL": "http://your-home-assistant:8123",
        "HA_TOKEN": "your_long_lived_access_token"
      }
    }
  }
}

可用工具

工具 说明
ha_health_check 检查是否可以访问Home Assistant API
ha_get_config 获取家庭助理配置
ha_list_entities 列出所有实体（可选按域筛选）
ha_get_entity_state 获取特定实体的状态
ha_list_services 列出可用服务
ha_call_service 呼叫任何家庭助理服务
ha_turn_on 启用具有可选参数的实体
ha_turn_off 关闭实体
ha_toggle 切换实体的状态
ha_get_history 获取历史状态更改
ha_fire_event 启动自定义事件

例子

一旦配置了Claude，您可以问：

  • “检查我的家庭助理是否在线”
  • “列出我所有的灯”
  • “以50%的亮度打开客厅灯”
  • “卧室里的温度是多少？”
  • “切换厨房开关”
  • “显示前门传感器的历史记录”

测试

运行所有测试

uv run pytest

跑步时覆盖

uv run pytest --cov=src/home_assistant_mcp --cov-report=html

仅运行单元测试

uv run pytest tests/unit

仅运行集成测试

uv run pytest tests/integration

开发工具

MCP构建器技能

该项目包括用于增强mcp服务器开发指导的官方Anthropic mcp构建器技能。

安装：

# Install or update the skill
./install-mcp-builder-skill.sh

# Update to latest version
./install-mcp-builder-skill.sh --update

# Install with Python dependencies for evaluation scripts
./install-mcp-builder-skill.sh --install-deps

可用资源：

  • Python MCP服务器指南： .claude/skills/mcp-builder/reference/python_mcp_server.md
  • 最佳实践： .claude/skills/mcp-builder/reference/mcp_best_practices.md
  • 评估工具： .claude/skills/mcp-builder/scripts/evaluation.py

使用Claude Code进行开发时，该技能会自动可用。

项目结构

ha_connection/
├── .claude/
│   └── skills/
│       └── mcp-builder/   # MCP development guidance skill
├── src/
│   └── home_assistant_mcp/
│       ├── __init__.py
│       ├── client.py      # Home Assistant REST API client
│       ├── config.py      # Configuration management
│       ├── models.py      # Pydantic data models
│       └── server.py      # MCP server implementation
├── tests/
│   ├── conftest.py        # Pytest fixtures
│   ├── unit/              # Unit tests
│   │   ├── test_client.py
│   │   ├── test_config.py
│   │   └── test_models.py
│   └── integration/       # Integration tests
│       └── test_server.py
├── .env.example           # Example environment configuration
├── install-mcp-builder-skill.sh  # Skill installation script
├── pyproject.toml         # Project configuration
└── README.md

安全说明

  • 永远不要承诺你的 .env 归档或公开您的访问令牌
  • 使用具有最低所需权限的令牌
  • 考虑对远程家庭助理实例使用HTTPS
  • 令牌授予API完全访问权限-将其视为密码

许可证

麻省理工学院

相关 MCP