Openwrt MCP Server

🚀 openwrt-mcp-server

openwrt-mcp-server is a lightweight and extensible MCP (Model Context Protocol) server designed to run on embedded routers and devices based on OpenWrt. It enables two-way communication between devices and external AI systems via MQTT and HTTP, using JSON-RPC 2.0 as the message format.

This server aims to provide a secure and structured interface for AI agents to:

• Query real-time device context (network, Wi-Fi, system metrics)
• Execute system-level commands remotely
• Support real-time command responses and context streaming

✨ Features

• Written in Rust for high performance and security
• Supports MQTT (via rumqttc) and HTTP (via warp)
• Compatible with JSON-RPC 2.0 for AI model integration
• Modular architecture for future extensibility
• Complete TOML configuration with all fields actually used in the code (see below)
• Secure HTTP API with token-based authentication (via the x-api-token header)
• All code comments and documentation are written in English to support international collaboration
• Clean compilation without warnings (all configuration fields are used)
• Low memory footprint, suitable for embedded OpenWrt targets

🌎 Use Cases

• AI-driven home gateway monitoring and orchestration
• Device fleet context reporting for edge management
• Automatic recovery and self-healing network policies via AI
• Integration with LLMs and orchestration pipelines (e.g., n8n, LangChain)

🛠️ Components

• context/collector.rs: Collects runtime state from OpenWrt (ubus, uci, ifstatus)
• mqtt/handler.rs: Handles MQTT connections, authentication, topic subscriptions (using all configuration fields), and schedules/responds to JSON-RPC commands
• http/routes.rs: RESTful API for status and command input, with all endpoints requiring token-based authentication
• executor/command.rs: Executes validated system-level instructions
• config/mod.rs: Loads and validates the complete .toml configuration, including all MQTT/HTTP fields
• All modules are documented in English

🛡️ Protocol

Follows JSON-RPC 2.0. See REQUIREMENTS.md for the full message schema.

🔧 Build

cargo build --release

Cross-compilation for OpenWrt (musl) is recommended for deployment.

🌐 Configuration

Example config.toml (all fields are required and used):

[mqtt]
broker = "mqtts://iot.example.com:8883"
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"

• All configuration fields are loaded and used in the codebase.
• MQTT uses client_id, username, password, and topic_prefix for connection and topic management.
• The HTTP server uses enable, listen_addr, port, and token for secure API access.

🚀 Roadmap

• [x] Initial MQTT + HTTP dual protocol support
• [x] Complete TOML configuration with all fields used in the code
• [x] JSON-RPC 2.0 command and context schema (scheduling and response logic in MQTT/HTTP)
• [x] Secure HTTP API with token-based authentication
• [x] All code comments and documentation written in English
• [ ] Context collector integration with UCI/UBUS/ifstatus
• [ ] Device functionality introspection (device.describe)
• [ ] WebSocket transport layer for real-time control
• [ ] Command allow list and sandboxing
• [ ] Plugin-based extensibility to support new command modules
• [ ] Streaming data telemetry metrics channel (e.g., /metrics)
• [ ] CLI interface for testing/debugging commands
• [ ] Optional gRPC support
• [ ] Documentation and example improvement