Matter Controller MCP

物质控制器MCP服务器

一个强大的模型上下文协议（MCP）服务器，提供全面的Matter设备控制功能。该服务器使AI助手和应用程序能够通过标准化的界面发现、调试和控制兼容Matter的智能家居设备。

](https://badge.fury.io/js/matter-controller-mcp)  ](https://nodejs.org/)

特性

• 🔌 设备管理：调试和停用自动连接的物质设备
• 💡 设备控制：控制灯、开关和其他物质设备
• 🎛️ 高级控制：支持调光、颜色控制和色温
• 📊 设备信息：检索详细的设备信息和功能结构
• 🔧 属性访问：直接读取和写入设备群集属性
• 🌐 多个传输：支持stdio、SSE和流式HTTP传输
• 🔧 灵活的配置：基于环境的配置选项

支持的设备类型

• 照明：开/关灯、可调光灯、彩色灯
• 开关：智能开关和插座
• 传感器：各种传感器类型（温度、湿度等）
• 还有更多：任何兼容Matter的设备

建筑

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│  MCP Server      │◄──►│  Matter Network │
│  (AI Assistant) │    │  (This Project)  │    │    (Devices)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

服务器充当MCP客户端和Matter设备之间的桥梁，为设备控制和监控提供标准化的接口。

安装

NPM包

npm install -g matter-controller-mcp

来源

git clone https://github.com/0x1abin/matter-controller-mcp.git
cd matter-controller-mcp
npm install
npm run build

用法

作为MCP服务器（默认-stdio传输）

npx matter-controller-mcp
# or
matter-controller-mcp

苏格兰和南方能源公司运输

npx matter-controller-mcp sse
# or
matter-controller-mcp sse

可流式HTTP传输

npx matter-controller-mcp streamableHttp
# or
matter-controller-mcp streamableHttp

光标MCP服务器

{
  "mcpServers": {
    "matter-controller": {
      "command": "npx",
      "args": ["-y", "matter-controller-mcp", "stdio"]
    }
  }
}

配置

服务器支持各种环境变量进行配置：

# Matter controller configuration
export MATTER_UNIQUE_ID="your-unique-controller-id"          # Controller unique identifier
export MATTER_ADMIN_FABRIC_LABEL="Your Matter Controller"    # Admin fabric label  
export MATTER_LOG_LEVEL="info"                               # Log level: debug, info, warn, error

# BLE support (optional)
export ble="true"        # Enable BLE support
export ble.hci.id="0"    # BLE HCI interface ID

# Server configuration
export PORT="3001"       # Port for HTTP/SSE transports

可用工具

设备管理

• get_controller_status：获取当前控制器状态
• commission_device：调试新的物质装置
• get_commissioned_devices：列出所有已调试的设备
• decommission_device：从网络中删除设备
• get_device_info：获取详细的设备信息

设备控制

• control_onoff_device：打开/关闭设备或切换
• control_level_device：控制亮度/调光（0-254）
• control_color_device：控制色温和色调/饱和度

高级功能

• read_attributes：从集群读取设备属性（特定属性或全部属性）
• write_attributes：将属性写入设备集群（支持批量写入）

API示例

调试设备

// Using manual pairing code
{
  "name": "commission_device",
  "arguments": {
    "pairingCode": "34970112332"
  }
}

// Using IP address and setup PIN
{
  "name": "commission_device",
  "arguments": {
    "ip": "192.168.1.100",
    "port": 5540,
    "setupPin": 20202021
  }
}

// Using BLE commissioning with WiFi credentials
{
  "name": "commission_device",
  "arguments": {
    "ble": true,
    "setupPin": 20202021,
    "longDiscriminator": 3840,
    "wifiSsid": "YourWiFiNetwork",
    "wifiCredentials": "YourWiFiPassword"
  }
}

控制装置

// Turn on a light
{
  "name": "control_onoff_device",
  "arguments": {
    "nodeId": "1234567890abcdef",
    "action": "on"
  }
}

// Set brightness
{
  "name": "control_level_device",
  "arguments": {
    "nodeId": "1234567890abcdef",
    "level": 128
  }
}

// Set color temperature (warm/cool white)
{
  "name": "control_color_device",
  "arguments": {
    "nodeId": "1234567890abcdef",
    "colorTemperature": 250
  }
}

// Set color (hue and saturation for colored lights)
{
  "name": "control_color_device",
  "arguments": {
    "nodeId": "1234567890abcdef",
    "hue": 120,
    "saturation": 200
  }
}

读取设备信息

// Get device details
{
  "name": "get_device_info",
  "arguments": {
    "nodeId": "1234567890abcdef"
  }
}

// Read specific attributes
{
  "name": "read_attributes",
  "arguments": {
    "nodeId": "1234567890abcdef",
    "clusterId": 6,  // OnOff cluster
    "endpointId": 1,
    "attributeIds": [0]  // OnOff attribute
  }
}

// Read all attributes in a cluster
{
  "name": "read_attributes",
  "arguments": {
    "nodeId": "1234567890abcdef",
    "clusterId": 6,  // OnOff cluster
    "endpointId": 1
  }
}

// Write attributes (batch writing supported)
{
  "name": "write_attributes",
  "arguments": {
    "nodeId": "1234567890abcdef",
    "clusterId": 6,  // OnOff cluster
    "endpointId": 1,
    "attributes": {
      "0": true  // Set OnOff attribute to true
    }
  }
}

发展

先决条件

• Node.js 18+
• TypeScript 5.6+
• Matter.js兼容系统
• BLE支持（可选，用于BLE调试）

构建

npm run build                # Build the project (compiles TypeScript)
npm run start                # Start with stdio transport (default)
npm run start:sse            # Start with SSE transport
npm run start:streamableHttp # Start with streamable HTTP transport

代码的风格

• 使用ES模块 .js 导入路径中的扩展
• 使用TypeScript严格键入所有函数和变量
• 遵循zod模式进行工具输入验证
• 比起回调和Promise链，更喜欢async/await
• 使用描述性变量名和适当的错误处理

贡献

我们欢迎捐款！请按照以下步骤操作：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

• 遵循现有的代码样式和模式
• 添加适当的错误处理和日志记录
• 更新新功能的文档
• 彻底测试您的更改
• 遵循语义版本控制发布

故障排除

常见问题

1. 找不到设备：确保设备处于配对模式并且位于同一网络上
2. 连接超时：检查网络连接和设备可用性
3. 权限错误：确保BLE访问的适当权限（如果使用BLE调试）
4. 端口冲突：如果使用HTTP/SSE传输，请更改PORT环境变量
5. 控制器初始化失败：检查Matter.js依赖关系和系统兼容性
6. 设备调试失败：验证配对码/PIN和网络连接

调试模式

启用调试日志以进行故障排除：

export MATTER_LOG_LEVEL="debug"

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• CHIP项目 -The Matter标准
• Matter.js -核心Matter协议实现
• MCP-SDK -MCP Typescript SDK
• 模型上下文协议 -协议规范

______________________________________________________________________

由以下材料制成❤️ 对于物质和MCP社区