mxchip-gateway-mcp 0.1.0

MCP server for MXCHIP local gateway (WebSocket)

mxchip-gateway-mcp

庆科本地网关 MCP Server。通过局域网 WebSocket（ws://{ip}:53248/ws）连接网关，提供 MCP Tool 查询与控制子设备、场景。

安装

需要 Python 3.10+ 与 uv（推荐）或 pip。

pip install mxchip-gateway-mcp
# 或
uvx mxchip-gateway-mcp

MCP 配置

在 Cursor（.cursor/mcp.json）或 Claude Code（.mcp.json）中添加：

{
  "mcpServers": {
    "mxchip-gateway-mcp": {
      "command": "uvx",
      "args": ["mxchip-gateway-mcp"]
    }
  }
}

可选通过 env 预置网关连接：

{
  "mcpServers": {
    "mxchip-gateway-mcp": {
      "command": "uvx",
      "args": ["mxchip-gateway-mcp"],
      "env": {
        "GATEWAY_IP": "192.168.1.100",
        "GATEWAY_PASSWORD": "mxchip-gateway-admin"
      }
    }
  }
}

锁定版本：

{
  "args": ["--from", "mxchip-gateway-mcp==0.1.0", "mxchip-gateway-mcp"]
}

网关连接

以下方式任选其一：

1. MCP 配置中的 GATEWAY_IP / GATEWAY_PASSWORD 环境变量
2. 用户配置目录下的 gateways.json（add_gateway 工具会自动写入）
   • macOS: ~/Library/Application Support/mxchip-gateway-mcp/gateways.json
   • Linux: ~/.config/mxchip-gateway-mcp/gateways.json
   • Windows: %APPDATA%/mxchip-gateway-mcp/gateways.json
3. 对话中调用 add_gateway 工具

可参考 gateways.json.example。

MCP Tools

Tool	说明
add_gateway	手动配置网关 IP 并建立连接
get_gateway_status	查看连接状态与重连信息
get_home	获取设备、场景、区域、群组等家庭模型
get_attributes	读取设备属性
set_attributes	设置设备属性（下行控制）
set_scenes	触发场景（下行控制）

Resource gateway://home 提供当前家庭状态快照（含上行 event 更新）。网关断线后后台自动重连。

开发

python3.10 -m venv .venv
.venv/bin/pip install -e ".[dev]"
mxchip-gateway-mcp
# 或
uvx --from . mxchip-gateway-mcp

构建与发布：

pip install build twine
python -m build
twine upload dist/*

调试

npx @modelcontextprotocol/inspector mxchip-gateway-mcp