Matter Controller MCP

What 0x1abin/matter-controller-mcp MCP server does

The 0x1abin/matter-controller-mcp MCP server connects an MCP client to Matter-compatible devices. It exposes operations for commissioning and removing devices, checking controller state, listing commissioned nodes, and retrieving device details including their capability structure.

Device control covers common lighting and switching tasks. The available controls can change an on/off state, toggle a device, set a dimming level from 0 to 254, and set color temperature or hue and saturation. The server also supports lower-level Matter interaction through cluster attribute reads and writes, including reading selected attributes, reading every attribute in a cluster, and submitting multiple attribute values in one write.

Supported examples include on/off lights, dimmable lights, color lights, smart switches, outlets, and various sensors. The README also describes support for other Matter-compatible device types, although the exposed high-level controls depend on the device capabilities.

How it works

The MCP client communicates with the server, which acts as the intermediary to the Matter network. The controller is initialized automatically when the process starts. A client can then commission a device using a manual pairing code, an IP address with a setup PIN, or BLE commissioning with Wi-Fi credentials. Once commissioned, devices can be addressed by node ID.

Transport selection is available at startup. The default is stdio; sse starts the SSE transport, and streamableHttp starts the streamable HTTP transport. HTTP and SSE deployments can use the PORT setting to select a listening port. BLE commissioning may require operating-system permissions and a compatible BLE interface.

The reset_controller operation clears controller storage and requires confirmation, so it should be treated as a destructive administrative action.

Setup and configuration

The published npm package is matter-controller-mcp. The 0x1abin/matter-controller-mcp MCP server requires Node.js 18 or newer, and the project documentation also lists TypeScript 5.6 or newer and a Matter.js-compatible system for development or execution.

For MCP clients using stdio, the package can be launched with npx -y matter-controller-mcp. Cursor configuration can use the same command with matter-controller-mcp and stdio as arguments. Source installation instead involves cloning the repository, running npm install, and building with npm run build.

Configuration is environment-based. MATTER_UNIQUE_ID sets the controller identifier, MATTER_ADMIN_FABRIC_LABEL sets its administrative fabric label, and MATTER_LOG_LEVEL controls logging verbosity. BLE can be enabled with the documented ble setting and assigned an HCI interface with ble.hci.id; these names are shown in the README as lowercase environment variables. PORT selects the port for SSE or streamable HTTP operation. Debug logging uses MATTER_LOG_LEVEL=debug.

Tools and capabilities

The MCP tool set includes:

• get_controller_status for controller state.
• commission_device and decommission_device for Matter device lifecycle management.
• get_commissioned_devices for listing nodes, with optional node ID filtering.
• get_device_info for device and capability details.
• control_onoff_device for on, off, and toggle actions.
• control_level_device for brightness or dimming.
• control_color_device for color temperature and hue/saturation.
• read_attributes and write_attributes for Matter cluster data, including batch writes.
• reset_controller for clearing controller storage after confirmation.

Limitations and notes

Commissioning depends on the device being available for pairing and, for network-based flows, reachable on the same network as the controller. Pairing codes, setup PINs, network connectivity, and device availability affect commissioning success. BLE commissioning additionally depends on system permissions and compatible hardware. Port conflicts can affect HTTP and SSE transports, while controller initialization depends on Matter.js dependencies and system compatibility.