Homeseer MCP

HomeSeer MCP服务器

用于控制HomeSeer智能家居设备的模型上下文协议（MCP）服务器，支持本地和云实例。

特性

• 通过MCP协议控制HomeSeer设备
• 使用过滤功能列出和搜索设备
• 检索和筛选HomeSeer事件（自动化操作）
• 执行HomeSeer事件（触发自动）
• 获取可用的设备控件
• 简单的本地网络访问（无需身份验证）
• 远程访问的用户名/密码身份验证
• 通过JSON文件或环境变量进行配置
• 支持本地和云HomeSeer实例
• 全面的测试套件

快速开始

1.安装

# Create and activate virtual environment
python -m venv venv

# Windows PowerShell:
.\venv\Scripts\Activate.ps1

# Linux/macOS:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2.启用本地网络访问（推荐）

对于本地同一子网访问（最简单）：

1. 在HomeSeer中，请访问 设置>网络
2. 启用“本地（同一子网）登录不需要密码”
3. 就是这样！从同一网络访问时不需要凭据

对于远程/云访问：

• 您需要HomeSeer用户名和密码
• 用于通过互联网或不同网络访问HomeSeer

3.配置连接

选项A:JSON配置文件（建议用于开发）

# Copy example configuration
cp config.json.example config.json

编辑 config.json 使用您的设置：

对于本地同一子网访问（最简单-不需要凭据）：

{
  "url": "http://192.168.1.100/JSON",
  "verify_ssl": false
}

使用用户名和密码进行远程/云访问：

{
  "url": "https://connected2.homeseer.com/json",
  "username": "your-username",
  "password": "your-password"
}

选项B：环境变量（建议用于生产）

# Windows PowerShell
$env:HOMESEER_URL = "http://192.168.1.100/JSON"
$env:HOMESEER_VERIFY_SSL = "false"

# Linux/macOS
export HOMESEER_URL="http://192.168.1.100/JSON"
export HOMESEER_VERIFY_SSL="false"

4.运行服务器

python server.py

或者使用VS Code任务：“运行MCP服务器”

配置

配置方法

服务器支持两种配置方法，优先级如下：

1. 默认值（硬编码）
2. JSON配置文件(config.json)
3. 环境变量（最高优先级-覆盖文件值）

配置选项

注： 对于启用了“无需密码”的本地同一子网访问，您不需要用户名/密码。

常见配置场景

本地HomeSeer实例（最简单-无需身份验证）：

如果您在HomeSeer中启用了“本地（同一子网）登录无需密码” 设置>网络 菜单中，您只需指定IP地址：

{
  "url": "http://192.168.1.100/JSON",
  "verify_ssl": false
}

不 username 或 password 需要！这是本地访问的最简单设置。

带用户名/密码的远程/云HomeSeer：

{
  "url": "https://connected2.homeseer.com/json",
  "username": "your-username",
  "password": "your-password"
}

仅环境变量（不需要config.json）：

# Local access
$env:HOMESEER_URL = "http://192.168.1.100/JSON"
$env:HOMESEER_VERIFY_SSL = "false"

# Or for remote access
$env:HOMESEER_URL = "https://connected2.homeseer.com/json"
$env:HOMESEER_USERNAME = "your-username"
$env:HOMESEER_PASSWORD = "your-password"

可用的MCP工具

服务器公开了以下MCP工具：

设备管理

• list_all_devices -列出所有具有可选过滤和房间信息的HomeSeer设备

- 参数： - free_text_search （可选）：按名称过滤设备 - need_room_information （可选）：包括位置详细信息 - 返回：带有ref、name和可选位置字段的设备列表

• get_device_info -通过参考ID获取特定设备的详细信息

- 参数： - device_ref：设备参考ID - 返回：详细的设备信息，包括名称、位置、值、状态和相关设备

• get_control -获取设备的可用控件列表

- 参数： - device_ref：设备参考ID - 返回：包含标签、值和控件类型的控件选项列表

设备控制

• control_homeseer_device -使用设备ID和控制ID控制设备

- 参数： - device_id：设备参考ID - control_id：要设置的控件/值ID - 返回：如果成功，则返回True

• control_homeseer_device_by_label -使用人类可读标签控制设备

- 参数： - device_ref：设备参考ID - label：控制标签（例如“开”、“关”、“关闭”） - 返回：如果成功，则返回True

活动管理

• get_events -通过可选筛选获取所有HomeSeer事件

- 事件是要执行的动作，例如控制灯、灯序列、恒温器等。 - 事件有两个属性：组名和事件名 - 参数： - free_text_search （可选）：按名称或组筛选事件（不区分大小写） - 返回：事件列表，每个事件包含： - Group：事件组名称（例如“照明”、“气候”） - Name：事件名称（例如，“车外灯关闭”） - id：唯一事件标识符 - 其他字段： voice_command, voice_command_enabled - 示例用法： - get_events() -获取所有事件 - get_events(free_text_search="lighting") -获取所有与照明相关的事件 - get_events(free_text_search="kitchen") -获取以“厨房”命名或分组的活动

• run_event -按组/名称或事件ID执行HomeSeer事件

- 触发自动化操作，如控制灯光、恒温器或运行顺序 - 参数： - group：事件组名称（如果使用名称，则为必填项，不区分大小写） - name：事件名称（使用组时需要，不区分大小写） - event_id：事件ID（组/名称的替代） - 返回：如果成功，则返回True - 注：必须提供 event_id 或两者 group 和 name - 示例用法： - run_event(group="Lighting", name="Outside Lights Off") -按名称运行事件 - run_event(event_id=5) -按ID运行事件 - run_event(group="Window Shutters", name="All house window shutters close") -执行快门事件

测试

快速测试：列出您的设备

from config import get_config
import requests

config = get_config()
print(f"Connecting to: {config.base_url}")

params = config.get_request_params(request="getstatus")
response = requests.get(
    config.base_url,
    params=params,
    timeout=config.timeout,
    verify=config.verify_ssl
)

print(f"Status: {response.status_code}")
if response.ok:
    data = response.json()
    print(f"Found {len(data.get('Devices', []))} devices")

运行测试套件

使用特定于平台的测试运行器：

# Windows PowerShell
.\test.ps1

# Windows Command Prompt
test.bat

# Linux/macOS
./test.sh

或者直接运行pytest：

# Run all tests
pytest tests/

# Verbose output
pytest tests/ -v

# With coverage report
pytest tests/ --cov=. --cov-report=html

测试套件包括：

• API客户端测试
• MCP服务器测试
• 配置管理测试

安全最佳实践

1. 永不承诺 config.json 持有真实证件

- 文件已在 .gitignore - 使用 config.json.example 作为模板

1. 尽可能使用本地同一子网访问

- 最简单的设置，无需凭据 - 在HomeSeer>设置>网络中启用“本地（同一子网）登录不需要密码” - 家庭网络使用最安全

1. 在生产中使用环境变量

- 尤其是在Docker/Kubernetes环境中 - 更容易安全地管理秘密 - 环境变量覆盖配置文件值

1. 在生产中启用SSL验证

- 仅禁用(verify_ssl: false)用于使用自签名证书进行测试 - 对于本地实例，考虑使用适当的SSL证书

故障排除

配置问题

问题： 配置未加载

• 解决方案： 确保 config.json 位于项目根目录中
• 解决方案： 验证JSON语法是否有效（使用JSON验证器）
• 解决方案： 检查文件权限

问题： 环境变量不起作用

• 解决方案： 确保变量前缀为 HOMESEER_
• 解决方案： 检查当前shell会话中是否设置了变量
• 解决方案： 变量名区分大小写

连接问题

问题： 认证失败

• 解决方案： 对于本地访问，请确保在HomeSeer>设置>网络中启用了“本地（同一子网）登录不需要密码”
• 解决方案： 对于远程访问，请验证您的用户名/密码是否正确
• 解决方案： 确保您的网络可以访问该URL
• 解决方案： 对于云HomeSeer，请使用 https://connected2.homeseer.com/json
• 解决方案： 在浏览器中或使用 curl

问题： SSL证书验证失败

• 发展： 集 "verify_ssl": false 在config.json中
• 生产： 在HomeSeer实例上安装正确的SSL证书

问题： 连接超时

• 解决方案： 验证HomeSeer是否正在运行且可访问
• 解决方案： 增加超时值（例如。， "timeout": 60)
• 解决方案： 检查防火墙设置

发展

热重新加载配置

from config import get_config_manager

# Reload configuration after making changes
manager = get_config_manager()
new_config = manager.reload_config()

调试日志记录

启用调试日志记录以查看详细的配置和API调用：

import logging
logging.basicConfig(level=logging.DEBUG)

项目结构

homeseer-mcp/
├── server.py              # Main MCP server implementation
├── config.py              # Configuration management
├── config.json.example    # Configuration template
├── requirements.txt       # Python dependencies
├── tests/                 # Test suite
│   ├── test_server.py    # Server and API client tests
│   ├── test_config.py    # Configuration tests
│   └── README.md         # Test documentation
├── test.ps1              # PowerShell test runner
├── test.bat              # Windows batch test runner
└── test.sh               # Unix/Linux test runner

API 文档

有关HomeSeer JSON API的详细信息，请参阅：

• HomeSeer JSON API文档

许可证

看 许可证 文件以获取详细信息。

贡献

欢迎投稿！请确保：

• 所有测试均通过(pytest tests/)
• 代码遵循现有模式
• 新功能包括测试
• 文档已更新

未来的增强功能

OAuth令牌身份验证： HomeSeer JSON API支持基于令牌的身份验证，这可以提供额外的安全优势。如果社区有兴趣，可以在未来的版本中添加OAuth令牌支持。目前，最简单的方法是使用本地同一子网访问（无凭据）或用户名/密码进行远程访问。