物质控制器MCP服务器
一个强大的模型上下文协议（MCP）服务器，提供全面的Matter设备控制功能。该服务器使AI助手和应用程序能够通过标准化的界面发现、调试和控制兼容Matter的智能家居设备。
特性
- 🔌 设备管理：调试和停用自动连接的物质设备
- 💡 设备控制：控制灯、开关和其他物质设备
- 🎛️ 高级控制：支持调光、颜色控制和色温
- 📊 设备信息：检索详细的设备信息和功能结构
- 🔧 属性访问：直接读取和写入设备群集属性
- 🌐 多个传输：支持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
- 使用描述性变量名和适当的错误处理
贡献
我们欢迎捐款！请按照以下步骤操作：
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
开发指南
- 遵循现有的代码样式和模式
- 添加适当的错误处理和日志记录
- 更新新功能的文档
- 彻底测试您的更改
- 遵循语义版本控制发布
故障排除
常见问题
- 找不到设备：确保设备处于配对模式并且位于同一网络上
- 连接超时：检查网络连接和设备可用性
- 权限错误：确保BLE访问的适当权限（如果使用BLE调试）
- 端口冲突：如果使用HTTP/SSE传输，请更改PORT环境变量
- 控制器初始化失败：检查Matter.js依赖关系和系统兼容性
- 设备调试失败：验证配对码/PIN和网络连接
调试模式
启用调试日志以进行故障排除：
export MATTER_LOG_LEVEL="debug"许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
______________________________________________________________________
由以下材料制成❤️ 对于物质和MCP社区