openwrt-mcp-server

What is openwrt-mcp-server?

openwrt-mcp-server is a Rust-based MCP-style bridge for OpenWrt and Linux edge devices. It exposes a single-device JSON-RPC control surface over HTTP and MQTT, with a long-term direction to run as a standalone fleet MCP service managing many OpenWrt devices through EdgePulse adapters.

How to use openwrt-mcp-server?

Build with cargo build --release, configure via config.toml (MQTT broker, HTTP listen address and token), then invoke the HTTP API endpoints (/api/context, /api/describe, /api/cmd) with the x-api-token header, or publish JSON-RPC requests to the MQTT command topic and subscribe to the response topic.

Key features of openwrt-mcp-server

• HTTP API using warp and MQTT transport via rumqttc.
• JSON-RPC 2.0 request/response envelopes.
• Token-protected HTTP endpoints via x-api-token header.
• TOML configuration with startup validation.
• Real context collection from OpenWrt ubus and Linux fallback.
• Allowlisted command execution with risk metadata.
• device.describe introspection for transports, commands, and context.
• Structured JSON logs for service, config, HTTP, and MQTT events.

Use cases of openwrt-mcp-server

• Remotely manage a single OpenWrt device from AI agents or orchestration tools.
• Collect device context (e.g., network status, system info) via HTTP or MQTT.
• Execute allowlisted commands (e.g., restart interface, get context) with introspection.
• Integrate as a local companion process for EdgePulse telemetry and policy enforcement.
• Serve as a future building block for multi-tenant fleet management and device registry.

FAQ from openwrt-mcp-server

How does openwrt-mcp-server authenticate requests?

HTTP endpoints require the x-api-token header matching the token configured in config.toml. MQTT authentication uses the configured username and password for broker connection.

What transport protocols are supported?

Currently, openwrt-mcp-server supports HTTP and MQTT transports, both using JSON-RPC 2.0.

Can I run openwrt-mcp-server on non-OpenWrt Linux devices?

Yes. The server collects context from ubus when available and falls back to /proc, /sys, and ip -j on generic Linux.

How do I discover available commands and capabilities?

Send a device.describe JSON-RPC request via HTTP or MQTT. The response includes lists of transports, commands, command risk metadata, and context collectors.

Are there plans for multi-device fleet management?

Yes. A standalone fleet server mode with device registry, rule-based access control, and multi-tenant isolation is planned. The current version operates as a single-device bridge.