mcp-kr-controller

MCP (Model Context Protocol) server for KR-series relay controllers. Connect your hardware controllers to AI through serial/UART, TCP, or UDP — zero configuration, conversational discovery.

Features

• Conversational Architecture — No config file needed. Tell the AI your connection type, it handles the rest.

• Multi-Transport — Serial (UART 9600 8N1), TCP, UDP with unified transport abstraction.

• Auto Discovery — Broadcast scan finds all connected devices, queries I/O channels and function modules, registers automatically.

• State Persistence — Device connections and registrations saved to state.json, auto-restored on restart.

• 23 MCP Tools — Auto discovery, device scanning, status query, relay control, PLC advanced control, animations, DI trigger automation.

• Fire-and-Forget — Control commands return instantly without waiting for hardware response.

Related MCP server: rosclaw-ur-rtde-mcp

Quick Start

Install

npm install -g mcp-kr-controller
# or use directly without install
npx mcp-kr-controller

Configure in your MCP client

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json, WorkBuddy mcp.json):

{
  "mcpServers": {
    "kr-controller": {
      "command": "npx",
      "args": ["mcp-kr-controller"],
      "type": "stdio"
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "kr-controller": {
      "command": "mcp-kr-controller",
      "type": "stdio"
    }
  }
}

Usage Flow

1. Confirm connection type — Tell the AI: "Search for devices"

   • AI will ask: "串口还是网络？" (Serial or Network?)

2. Network — AI calls auto_discover(connection_type="network")

   • Auto-tries V4 TCP 192.168.16.254:8080 and V5 UDP broadcast 192.168.1.255:8080

   • Multi-NIC: auto-matches local NIC to the same subnet (255.255.255.0)

   • Devices found are automatically registered with I/O config

3. Serial — AI asks for COM port, then calls auto_discover(connection_type="serial", path="COM3")

   • Connects via RS-485 at 9600 baud, scans and registers devices

4. Control — Say "Turn on channel 3 of device 1" — AI handles the rest

If default addresses don't match your network, use setup_connection with manual config.

Multi-NIC Note: The V5 UDP discovery automatically selects the local NIC matching the target subnet (255.255.255.0). If you have multiple network cards, make sure the controller is on the same subnet as one of them.

Hardware Support

Two hardware versions, three transport modes — all share the same control protocol.

Tested configurations (as of 2026-07-30):

Environment Variables (optional)

Protocol

KR-series controllers use an 8-byte fixed-length frame protocol over UART (9600 bps, 8N1):

| Header | Address | Command | Data0 | Data1 | Data2 | Data3 | Checksum |
|  1 byte | 1 byte  | 1 byte  | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte   |

• Header: 0x55 (request) / 0x22 (response)

• Address: 0x00/0xFF (broadcast) or 0x01–0xFE (device address 1-254)

• Checksum: sum(byte[0..6]) & 0xFF

Supported Commands

MCP Tools

Connection Management

• setup_connection — Establish serial/TCP/UDP connection

• list_connections — List active connections

• remove_connection — Remove a connection

Device Discovery

• scan_devices — Broadcast scan + auto-register devices

• list_devices — Show registered devices

Status & Query

• read_status — Read DI inputs + relay outputs

• get_function_modules — Query function module bitmask

Basic Control

• connect_relay — Connect (energize) one relay

• disconnect_relay — Disconnect (de-energize) one relay

• set_relays_by_mask — Set all relays by bitmask

• all_relays_on / all_relays_off — All relays on/off

Advanced Control

• momentary_on_off_single / momentary_off_on_single — Momentary action (single channel)

• momentary_on_off_multi / momentary_off_on_multi — Momentary action (by mask)

• blink_single / blink_multi — Blink relay(s)

• group_connect / group_disconnect / group_toggle — Group operations

Animation Test

• ping_pong — Ping-pong bounce animation with configurable delay

Event Trigger

• wait_di_trigger — Monitor DI channel, execute action on rising edge

Development

# Clone
git clone https://github.com/kinbeg/mcp-kr-controller.git
cd mcp-kr-controller

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev

Purchase

KR-series controllers are available at the official store:

kinbeg.taobao.com

License

MIT