openwrt-mcp-server

openwrt-mcp-server is a Rust-based MCP-style bridge for OpenWrt and Linux edge devices. Today it exposes a single-device JSON-RPC control surface over HTTP and MQTT. The long-term direction is to let the Rust server also run outside OpenWrt as a standalone fleet MCP service that can manage many OpenWrt devices through EdgePulse and other device adapters.

Current deployment modes:

• Local OpenWrt or Linux companion process for one device.
• Remote bridge endpoint for AI agents and orchestration systems.
• Future standalone fleet server with device registry, rule-based access control, and multi-tenant isolation.

Current Capabilities

• HTTP API using warp.
• MQTT transport using rumqttc.
• JSON-RPC 2.0 request and response envelopes.
• Token-protected HTTP endpoints via the x-api-token header.
• TOML configuration with startup validation.
• Real context collection from OpenWrt ubus, with Linux fallback data from /proc, /sys, and ip -j.
• Allowlisted command execution for supported device actions.
• device.describe capability introspection for transports, commands, command risk metadata, and context collectors.
• Lightweight command and context registries as extension points for future modules.
• Structured JSON logs for service, config, HTTP, and MQTT events.
• JSON Schema documentation for command and context payloads under schema/.

Project Layout

• src/context/collector.rs: Collects device context.
• src/context/registry.rs: Declares built-in context collectors and extension metadata.
• src/executor/command.rs: Dispatches allowlisted commands.
• src/executor/registry.rs: Declares command names, required args, and risk levels.
• src/http/routes.rs: Exposes authenticated HTTP JSON-RPC endpoints.
• src/mqtt/handler.rs: Handles MQTT subscription, dispatch, and response publishing.
• src/config/mod.rs: Loads and validates config.toml.
• src/logging.rs: Emits compact JSON log records.
• src/model/types.rs: Defines shared request/result/context types.
• schema/: Contains JSON Schema files for documented payload shapes.
• docs/edgepulse-integration-roadmap.md: Describes EdgePulse, fleet, RBAC, and multi-tenant plans.

Build and Test

cargo build --release
cargo test

For OpenWrt deployment, cross-compile with the OpenWrt SDK or a musl target appropriate for the device.

Configuration

Example config.toml:

[mqtt]
broker = "mqtt://localhost:1883"
client_id = "openwrt-one"
username = "mcp-user"
password = "mcp-pass"
topic_prefix = "mcp/device/openwrt-one"

[http]
enable = true
listen_addr = "0.0.0.0"
port = 8080
token = "your-api-token"

Validation currently rejects:

• Empty mqtt.broker, mqtt.client_id, or mqtt.topic_prefix.
• MQTT topic prefixes containing + or #.
• Invalid http.listen_addr.
• http.port = 0.
• Empty http.token when HTTP is enabled.

HTTP API

All HTTP endpoints require:

x-api-token: <configured token>

Get current context:

curl -H 'x-api-token: change-me' \
  http://127.0.0.1:8080/api/context

Describe server capabilities:

curl -H 'x-api-token: change-me' \
  http://127.0.0.1:8080/api/describe

Execute an allowlisted command:

curl -H 'x-api-token: change-me' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"device.executeCommand","params":{"command":"get_context"},"id":"cmd-1"}' \
  http://127.0.0.1:8080/api/cmd

Supported built-in commands are declared in src/executor/registry.rs.

MQTT API

Command topic:

{topic_prefix}/cmd

Response topic:

{topic_prefix}/resp

Example capability request:

{
  "jsonrpc": "2.0",
  "method": "device.describe",
  "params": {},
  "id": "describe-1"
}

Example command request:

{
  "jsonrpc": "2.0",
  "method": "device.executeCommand",
  "params": {
    "command": "restart_interface",
    "args": {
      "interface": "wan"
    }
  },
  "id": "c

... [View full README on GitHub](https://github.com/morninglight-el/openwrt-mcp-server#readme)