OpenWrt MCP

What OpenWrt MCP does

OpenWrt MCP connects an MCP client to a router running stock OpenWrt. It can report system health, inspect logs and network clients, examine firewall rules, run network diagnostics, read and modify UCI configuration, manage services and packages, inspect WireGuard peers, discover ubus APIs, and execute individual programs under an explicit access policy.

The server is designed for administrative work that needs review and recovery. Configuration changes are checked before commit, can be probed after reload, and remain armed for rollback until confirmed. A pending change is restored when the server starts again if it was not confirmed, including after a power cycle. Firmware tools can list preserved files, validate an image, check upgrade readiness, and create a backup, but they never flash the router.

How it works

The binary runs on the router and communicates with the MCP client through an SSH session. It supports stdio over SSH using a key-bound forced command, as well as HTTP over an SSH tunnel. The service listens on loopback and a root-only socket and does not make outbound connections or send telemetry on its own.

Access is deny-by-default. Grants can be scoped to tools, expire, and be rate-limited; optional TOTP can unlock tools protected by MFA. Operations that may cause the router or its package system to contact external services identify that behavior and require a grant. Tool output masks secrets by default, and newly generated WireGuard private keys are kept out of the conversation unless explicitly requested.

Setup and configuration

The router must run stock OpenWrt 24.10 or 25.12 with fw4/nftables. Nothing needs to be installed beforehand on the router. The release includes architecture-specific binaries and an install script that reads the router architecture; supported targets include ARM, MIPS, x86, and RISC-V variants. A PC needs OpenSSH. Building from source requires Go 1.26 or newer, SSH, and tar.

Package operations select apk when available and otherwise use opkg. OpenWrt 25.12 uses apk, while 24.10 uses opkg and has fewer package query and audit capabilities. Older fw3-based systems receive limited firewall support and should be treated as best effort.

Tools and capabilities

• Inspect status, health findings, security findings, logs, connected clients, routes, policy rules, neighbors, channel airtime, and interface traffic.
• Read UCI configuration, revisions, retained history, diffs, and cross-configuration references.
• Stage, validate, commit, probe, confirm, restore, or roll back UCI changes.
• Query, simulate, apply, review, and resolve package changes, including .apk-new or opkg-new configuration files.
• List and control procd services, with protections against stopping or disabling core access and networking services.
• Review nftables/fw4 output, manage WireGuard peers, query ubus, and run one non-shell program at a time.

Limitations and notes

The server does not flash firmware. The exec tool does not provide a shell by default, but granting shell-equivalent programs such as sh, find, awk, env, or ssh requires an explicit shell-equivalent option. Large ubus responses are pruned when they exceed the response limit.

Wireless survey data measures the channel currently used by each radio; other channels are not measured and are not recommended. WireGuard peer changes on OpenWrt 24.10 briefly restart tunnel sessions because that release must re-run the interface setup. Firmware derived from OpenWrt, including GL.iNet and ImmortalWrt, is supported on a best-effort basis.