@iobroker/mcp-server

@iobroker/mcp-server — 智能家居 MCP 服务

技能简介

@iobroker/mcp-server 是 ioBroker 智能家居平台的官方 MCP（Model Context Protocol）服务器。它将 ioBroker 完整暴露为符合 MCP 协议的服务端，使 Claude Desktop 等 MCP 客户端能够通过结构化工具读取和控制用户的智能家居设备、状态、对象、日志和文件系统。

核心能力

• MCP Streamable HTTP 传输：标准 /mcp 端点，支持 GET/POST/DELETE，兼容所有 MCP 客户端
• 双运行模式：可独立运行（自有 Web 服务器），也可作为 ioBroker web 适配器的扩展运行
• 完整认证体系：支持 HTTP Basic、持有者令牌、OAuth2（浏览器登录）三种认证方式
• 细粒度权限控制：可按用户 ACL 控制读写权限，写操作需单独授权
• SSL/TLS 支持：可配置 HTTPS，也支持反向代理场景
• 25 个 MCP 工具：覆盖状态读取、对象查询、设备列表、历史数据、文件操作、日志、系统诊断等全部能力
• SSE 实时推送：通过 MCP Resources 订阅状态/对象/日志变更，实时推送到客户端
• OAuth 发现协议：MCP 客户端只需端点 URL，剩余认证流程自动在浏览器完成

安装配置

前提条件：已安装 ioBroker 并运行（建议 js-controller 4.0+）

方式一：Admin UI 安装（推荐）

1. 登录 ioBroker Admin 界面
2. 进入「适配器」标签页，搜索「mcp」
3. 点击「+」安装 @iobroker/mcp-server
4. 安装完成后在实例列表点击扳手图标进入配置

方式二：命令行安装

iobroker install mcp-server
iobroker start

配置参数说明

使用步骤

第一步：配置并启动服务器

在 Admin 配置页面填写端口、绑定地址，打开「启用认证」并设置默认用户。保存后实例自动启动。

第二步：在 Claude Desktop 连接

在 Claude Desktop 配置文件中添加（独立模式）：

"mcpServers": {
  "iobroker": {
    "command": "npx",
    "args": ["-y", "@iobroker/mcp-server"]
  }
}

或（Web 扩展模式，端口 8082）：

"mcpServers": {
  "iobroker": {
    "url": "http://localhost:8082/mcp/"
  }
}

第三步：用自然语言控制设备

重启 Claude Desktop 后即可使用自然语言：

查询所有灯的状态
把客厅的灯打开
查看今天上午的温度历史曲线
列出所有可安装的适配器

第四步：配置写入权限（如需）

默认所有工具为只读。如需控制设备，在 Admin 配置中开启「允许设置状态」和「允许对象/文件更改」。

适用场景

• 家庭自动化控制：用自然语言查询和控制全屋灯光、空调、窗帘
• 设备状态监控：实时查看传感器数据（温度/湿度/能耗）并设置告警
• 智能家居调试：通过 ping_host、get_logs 等工具诊断设备连接问题
• 能耗分析：查询历史数据，分析用电高峰时段
• 多系统集成管理：统一管理来自不同品牌（Zigbee、Z-Wave、MQTT 等）的设备

适用人群

• 已在使用 ioBroker 的智能家居用户
• 希望通过 AI（Claude）自然语言控制家居设备的用户
• 需要将 ioBroker 集成到 AI Agent 工作流的开发者
• 家庭自动化爱好者和专业集成商

工作原理

ioBroker MCP Server 基于 Model Context Protocol 实现。服务器在 ioBroker js-controller 上注册一组工具（Tools），每个工具对应 ioBroker 的一个 API 操作。当 MCP 客户端（如 Claude Desktop）发送请求时，服务器将请求路由到对应的 ioBroker 适配器，执行状态读写或对象操作，并通过 MCP 协议返回结构化结果。

状态和对象还通过 MCP Resources 机制暴露为 URI 资源（iobstate://、iobobject://），支持订阅变更通知（SSE），客户端可实时接收家中设备的变化。

官方链接

• npm：https://npmjs.com/package/@iobroker/mcp-server
• GitHub：https://github.com/iobroker/ioBroker.mcp
• 官方文档：https://github.com/iobroker/ioBroker.mcp#readme
• ioBroker 官网：https://www.iobroker.net