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.

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.

Version	Transport	Product Line
V5	TCP / UDP (network)	8DI, 8DI+8DO, 12DI+8DO, 2DI+9DO, 16DI, 16DO
V4	RS-485 serial, TCP/UDP transparent	Various I/O configurations

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

Device	Ver	I/O	Transport	Status
#1	V5	12DI+8DO	UDP broadcast	Verified
#1	V4	16DO	TCP transparent	Verified
#21	V4	8DI+8DO	RS-485 COM3	Verified

Environment Variables (optional)

Variable	Description
KR_SERIAL_PATH	Serial port path (e.g. COM3, /dev/ttyUSB0)
KR_TCP_HOST	TCP host
KR_TCP_PORT	TCP port (default 8080)
KR_UDP_HOST	UDP host
KR_UDP_PORT	UDP port (default 8080)

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

Code	Function
0x21	Find devices (broadcast)
0x2D	Query device properties (I/O count, modules)
0x10	Read status (DI + relay)
0x11	Disconnect one relay
0x12	Connect one relay
0x13	Set relays by bitmask
0x06/0x08	Momentary on/off (by mask)
0x09/0x18	Momentary on/off (single channel)
0x07/0x17	Blink (single/multi)
0x14/0x15/0x16	Group disconnect/connect/toggle

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

PLC 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

• 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