# OpenWrt MCP [Health: Active]

**Category:** 📟 Embedded System  
**Repository:** https://github.com/stanislav-testhub/openwrt-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/openwrt-mcp

## Description
MCP server that runs on an OpenWrt router: deny-by-default policy, audit log, rollback-armed changes

## Tools
Capabilities this server exposes over MCP:

- **system_status** — Model, release, uptime, load, memory, storage, temperatures, conntrack, every interface (state, addresses, default route, errors), radios/SSIDs, and what is outstanding. Call first. `mode=doctor` returns ranked health findings (radio down, interface without an address, enabled service that died, co…
- **logread** — Whole log buffer filtered (substring, RE2, last N minutes) *before* the line limit; `offset` pages back from the newest line. `mode=summary` collapses it to distinct messages (numbers, addresses and ids become placeholders) with count, first and last time and worst severity. `baseline=save` returns…
- **network_clients** — DHCP leases + static hosts + neighbour table + every AP's association list, joined by MAC: name, IP, SSID, signal, rates, connected time, each client's share of its radio's airtime (from hostapd), lease; 100 rows a page, `offset` for the next.
- **firewall_show** — nft list ruleset`, `fw4 print`, `fw4 check`, one table or chain.
- **net_diag** — ping / traceroute / nslookup (optionally from a given interface), routes, policy rules, neighbours. `wifi_survey` reports, per radio, how busy the channel it stays on has been (busy, rx and tx airtime, noise); other channels are unmeasured, so it never recommends one. `traffic` samples interface ra…
- **uci_get** — uci show`, optionally with stable `cfgXXXXXX` ids. Ends with the config's **revision**. `history=list` / `diff:<id>` shows the kept versions from before each confirmed change. `refs=NAME` finds what defines and uses a name across configs.
- **uci_apply** — Stage, check, commit, reload, **rollback armed**. `dry_run` shows exactly what would change and what the service's own checker says. `expected_revisions` refuses if a config moved meanwhile, `probe` checks the router afterwards, `restore=<id>` puts a past version back. After the commit the config i…
- **uci_confirm** — Make a pending change permanent / undo it now.
- **service_list** — procd services; `service_list detail=NAME` returns an installed add-on's own status (tailscale, AdGuard Home, podkop; the plain list names the ones installed here); stopping or disabling dropbear, network, rpcd or openwrt-mcp is refused. `service_control` waits for the state to settle (`wait`) and…
- **pkg_query** — installed, upgradable, search, info, files, owner, policy, `apk audit`, world; 200 lines a page, `offset` for the next.
- **pkg_change** — apk add/del/upgrade; **simulates unless `commit=true`**; reports new `.apk-new` files; checks `/etc/apk/world` afterwards.
- **pkg_config_diff** — Every `.apk-new` as a diff against the live file -- for `/etc/config/*` by setting (`uci show`), so quoting/indentation noise disappears.
- **pkg_config_resolve** — keep_current (drop the new default) or use_new (install it; rollback-armed for UCI configs).
- **sysupgrade** — list (preserved files), test (validate an image in /tmp), check (`owut`), backup (mode 0600; the previous archive this tool made is removed). **Never flashes.
- **wg_list_clients** — Peers with handshake age, endpoint, traffic, config/kernel mismatch, duplicate names.
- **wg_new_client** — Keypair, next free address, peer saved in the network config; `uci_confirm` keeps it. The private key and config go to a root-only file; you collect them with `openwrt-mcp wg-show <name>` (config and QR in your own terminal). `reveal=true` returns them in the result instead.
- **wg_remove_client** — By name, key or section, from the config and the interface; rollback armed (`uci_confirm` keeps it). Refuses a peer connected in the last 3 minutes, or this session's own, unless `force=true`.
- **ubus_list** — Discovery: every object, method and argument signature.
- **ubus_call** — Anything else on the bus. Replies over 8 KB have long arrays pruned.
- **exec** — One program, no shell. A grant for `sh`, `find`, `awk`, `env`, `ssh` and the like is a root shell: `allow` refuses it without `--shell-equivalent`.
- **mfa_unlock** — Opens the TOTP window for MFA-gated tools.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/openwrt-mcp/readme_