使用说明

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.启用本地网络访问（推荐）

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

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

对于远程/云访问：

您需要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服务器”

配置

配置方法

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

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

配置选项

选项	环境变量	描述	默认值
`url`	`HOMESEER_URL`	HomeSeer API端点	`https://connected2.homeseer.com/json`
`username`	`HOMESEER_USERNAME`	用户名（用于远程访问）	无
`password`	`HOMESEER_PASSWORD`	密码（用于远程访问）	无
`source`	`HOMESEER_SOURCE`	请求标识符	`homeseer-mcp`
`timeout`	`HOMESEER_TIMEOUT`	请求超时（秒）	`30`
`verify_ssl`	`HOMESEER_VERIFY_SSL`	启用SSL验证	`true`

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

常见配置场景

本地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服务器测试
配置管理测试

安全最佳实践

永不承诺 config.json 持有真实证件
- 文件已在 .gitignore
- 使用 config.json.example 作为模板
尽可能使用本地同一子网访问
- 最简单的设置，无需凭据
- 在HomeSeer>设置>网络中启用“本地（同一子网）登录不需要密码”
- 家庭网络使用最安全
在生产中使用环境变量
- 尤其是在Docker/Kubernetes环境中
- 更容易安全地管理秘密
- 环境变量覆盖配置文件值
在生产中启用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令牌支持。目前，最简单的方法是使用本地同一子网访问（无凭据）或用户名/密码进行远程访问。