Matter Controller MCP Server

1# Matter Controller MCP Server
2 
3A powerful Model Context Protocol (MCP) server that provides comprehensive Matter device control capabilities. This server enables AI assistants and applications to discover, commission, and control Matter-compatible smart home devices through a standardized interface.
4 
5[![npm version](https://badge.fury.io/js/matter-controller-mcp.svg)](https://badge.fury.io/js/matter-controller-mcp)
6[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7[![Node.js Version](https://img.shields.io/node/v/matter-controller-mcp.svg)](https://nodejs.org/)
8 
9## Features
10 
11- **🔌 Device Management**: Commission and decommission Matter devices with automatic connection
12- **💡 Device Control**: Control lights, switches, and other Matter devices
13- **🎛️ Advanced Controls**: Support for dimming, color control, and color temperature
14- **📊 Device Information**: Retrieve detailed device information and capabilities structure
15- **🔧 Attribute Access**: Read and write device cluster attributes directly
16- **🌐 Multiple Transports**: Support for stdio, SSE, and streamable HTTP transports
17- **🔧 Flexible Configuration**: Environment-based configuration options
18 
19## Supported Device Types
20 
21- **Lighting**: On/off lights, dimmable lights, color lights
22- **Switches**: Smart switches and outlets
23- **Sensors**: Various sensor types (temperature, humidity, etc.)
24- **And more**: Any Matter-compatible device
25 
26## Architecture
27 
28```
29┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
30│   MCP Client    │◄──►│  MCP Server      │◄──►│  Matter Network │
31│  (AI Assistant) │    │  (This Project)  │    │    (Devices)    │
32└─────────────────┘    └──────────────────┘    └─────────────────┘
33```
34 
35The server acts as a bridge between MCP clients and Matter devices, providing a standardized interface for device control and monitoring.
36 
37## Installation
38 
39### NPM Package
40 
41```bash
42npm install -g matter-controller-mcp
43```
44 
45### From Source
46 
47```bash
48git clone https://github.com/0x1abin/matter-controller-mcp.git
49cd matter-controller-mcp
50npm install
51npm run build
52```
53 
54## Usage
55 
56### As MCP Server (Default - stdio transport)
57 
58```bash
59npx matter-controller-mcp
60# or
61matter-controller-mcp
62```
63 
64### SSE Transport
65 
66```bash
67npx matter-controller-mcp sse
68# or
69matter-controller-mcp sse
70```
71 
72### Streamable HTTP Transport
73 
74```bash
75npx matter-controller-mcp streamableHttp
76# or
77matter-controller-mcp streamableHttp
78```
79 
80### Cursor MCP Server
81 
82```json
83{
84  "mcpServers": {
85    "matter-controller": {
86      "command": "npx",
87      "args": ["-y", "matter-controller-mcp", "stdio"]
88    }
89  }
90}
91```
92 
93## Configuration
94 
95The server supports various environment variables for configuration:
96 
97```bash
98# Matter controller configuration
99export MATTER_UNIQUE_ID="your-unique-controller-id"          # Controller unique identifier
100export MATTER_ADMIN_FABRIC_LABEL="Your Matter Controller"    # Admin fabric label  
101export MATTER_LOG_LEVEL="info"                               # Log level: debug, info, warn, error
102 
103# BLE support (optional)
104export ble="true"        # Enable BLE support
105export ble.hci.id="0"    # BLE HCI interface ID
106 
107# Server configuration
108export PORT="3001"       # Port for HTTP/SSE transports
109```
110 
111## Available Tools
112 
113### Device Management
114 
115- **`get_controller_status`**: Get current controller status
116- **`commission_device`**: Commission a new Matter device
117- **`get_commissioned_devices`**: List all commissioned devices
118- **`decommission_device`**: Remove a device from the network
119- **`get_device_info`**: Get detailed device information
120 
121### Device Control
122 
123- **`control_onoff_device`**: Turn devices on/off or toggle
124- **`control_level_device`**: Control brightness/dimming (0-254)
125- **`control_color_device`**: Control color temperature and hue/saturation
126 
127### Advanced Features
128 
129- **`read_attributes`**: Read device attributes from clusters (specific attributes or all)
130- **`write_attributes`**: Write attributes to device clusters (supports batch writing)
131 
132## API Examples
133 
134### Commission a Device
135 
136```typescript
137// Using manual pairing code
138{
139  "name": "commission_device",
140  "arguments": {
141    "pairingCode": "34970112332"
142  }
143}
144 
145// Using IP address and setup PIN
146{
147  "name": "commission_device",
148  "arguments": {
149    "ip": "192.168.1.100",
150    "port": 5540,
151    "setupPin": 20202021
152  }
153}
154 
155// Using BLE commissioning with WiFi credentials
156{
157  "name": "commission_device",
158  "arguments": {
159    "ble": true,
160    "setupPin": 20202021,
161    "longDiscriminator": 3840,
162    "wifiSsid": "YourWiFiNetwork",
163    "wifiCredentials": "YourWiFiPassword"
164  }
165}
166```
167 
168### Control Device
169 
170```typescript
171// Turn on a light
172{
173  "name": "control_onoff_device",
174  "arguments": {
175    "nodeId": "1234567890abcdef",
176    "action": "on"
177  }
178}
179 
180// Set brightness
181{
182  "name": "control_level_device",
183  "arguments": {
184    "nodeId": "1234567890abcdef",
185    "level": 128
186  }
187}
188 
189// Set color temperature (warm/cool white)
190{
191  "name": "control_color_device",
192  "arguments": {
193    "nodeId": "1234567890abcdef",
194    "colorTemperature": 250
195  }
196}
197 
198// Set color (hue and saturation for colored lights)
199{
200  "name": "control_color_device",
201  "arguments": {
202    "nodeId": "1234567890abcdef",
203    "hue": 120,
204    "saturation": 200
205  }
206}
207```
208 
209### Read Device Information
210 
211```typescript
212// Get device details
213{
214  "name": "get_device_info",
215  "arguments": {
216    "nodeId": "1234567890abcdef"
217  }
218}
219 
220// Read specific attributes
221{
222  "name": "read_attributes",
223  "arguments": {
224    "nodeId": "1234567890abcdef",
225    "clusterId": 6,  // OnOff cluster
226    "endpointId": 1,
227    "attributeIds": [0]  // OnOff attribute
228  }
229}
230 
231// Read all attributes in a cluster
232{
233  "name": "read_attributes",
234  "arguments": {
235    "nodeId": "1234567890abcdef",
236    "clusterId": 6,  // OnOff cluster
237    "endpointId": 1
238  }
239}
240 
241// Write attributes (batch writing supported)
242{
243  "name": "write_attributes",
244  "arguments": {
245    "nodeId": "1234567890abcdef",
246    "clusterId": 6,  // OnOff cluster
247    "endpointId": 1,
248    "attributes": {
249      "0": true  // Set OnOff attribute to true
250    }
251  }
252}
253```
254 
255## Development
256 
257### Prerequisites
258 
259- Node.js 18+ 
260- TypeScript 5.6+
261- Matter.js compatible system
262- BLE support (optional, for BLE commissioning)
263 
264### Build
265 
266```bash
267npm run build                # Build the project (compiles TypeScript)
268npm run start                # Start with stdio transport (default)
269npm run start:sse            # Start with SSE transport
270npm run start:streamableHttp # Start with streamable HTTP transport
271```
272 
273### Code Style
274 
275- Use ES modules with `.js` extension in import paths
276- Strictly type all functions and variables with TypeScript
277- Follow zod schema patterns for tool input validation
278- Prefer async/await over callbacks and Promise chains
279- Use descriptive variable names and proper error handling
280 
281## Contributing
282 
283We welcome contributions! Please follow these steps:
284 
2851. Fork the repository
2862. Create a feature branch (`git checkout -b feature/amazing-feature`)
2873. Commit your changes (`git commit -m 'Add some amazing feature'`)
2884. Push to the branch (`git push origin feature/amazing-feature`)
2895. Open a Pull Request
290 
291### Development Guidelines
292 
293- Follow the existing code style and patterns
294- Add appropriate error handling and logging
295- Update documentation for new features
296- Test your changes thoroughly
297- Follow semantic versioning for releases
298 
299## Troubleshooting
300 
301### Common Issues
302 
3031. **Device not found**: Ensure the device is in pairing mode and on the same network
3042. **Connection timeout**: Check network connectivity and device availability  
3053. **Permission errors**: Ensure proper permissions for BLE access (if using BLE commissioning)
3064. **Port conflicts**: Change the PORT environment variable if using HTTP/SSE transport
3075. **Controller initialization failed**: Check Matter.js dependencies and system compatibility
3086. **Device commissioning failed**: Verify pairing code/PIN and network connectivity
309 
310### Debug Mode
311 
312Enable debug logging for troubleshooting:
313 
314```bash
315export MATTER_LOG_LEVEL="debug"
316```
317 
318## License
319 
320This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
321 
322 
323## Acknowledgments
324 
325- [Project CHIP](https://github.com/project-chip) - The Matter standard
326- [Matter.js](https://github.com/project-chip/matter.js) - The core Matter protocol implementation
327- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - The MCP Typescript SDK
328- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
329 
330---
331 
332Made with ❤️ for the Matter and MCP communities
333