Skip to main content
Glama

openwrt-mcp -- an MCP server for OpenWrt 24.10 and 25.12

English · Русский · 简体中文

CI Release License: MIT OpenWrt 24.10+ M8ven Score

An MCP server that runs on an OpenWrt router, so Claude Code (or any MCP client) can inspect and change it -- behind deny-by-default policies, an audit log, and an automatic rollback for configuration changes.

Local and private. The server makes no outbound connections of its own and sends no telemetry; it listens on loopback and on a root-only socket, and talks to your client over an SSH session you set up. The tools that can make the router itself reach out (net_diag, pkg_query with refresh, pkg_change, sysupgrade check, the uci_apply probes, ubus_call, exec) say so in their MCP annotations (openWorldHint), and each needs a grant from you. Secret values are masked in tool output by default, and a new WireGuard key never enters the conversation unless you ask for it.

Footprint. One static binary with no dependencies: 9.1 to 11.3 MB for the router architectures (9.6 MB on arm64, about 3.7 MB compressed in the release archive), about 10 MB resident on a GL-MT6000 right after start, and 23 tools in about 22 KB of tool descriptions. Every release file is checksummed and carries a build attestation.

Resident / anonymous (VmRSS / RssAnon)

Idle daemon

One bridge

Daemon after the golden calls

amd64, build host

10.9 / 1.8 MB

10.9 / 2.1 MB

17.6 / 7.3 MB

x86-64 in the 24.10.8 and 25.12.5 rootfs (CI, two runs each)

10.5 to 10.7 / 1.8 to 2.0 MB

10.2 to 10.3 / 1.6 to 1.8 MB

16.4 to 16.8 / 6.5 to 6.9 MB

mipsle-softfloat, 25.12.6 system emulation

10.3 / – MB

10.0 / 0.9 MB

16.3 / 5.2 MB

bench/footprint.sh; the stripped binary is 11.6 MB on amd64 (11.4 MB in the CI rootfs run) and 12.4 MB on mipsle. Resident includes the mapped binary, so anonymous memory is what memory_limit and the small profile act on. The CI row is the lowest and highest of four job summaries (the figures move by a few hundred kB between runs); the MIPS row is QEMU system emulation, not a router, see docs/resource-footprint.md.

Based on GlassOnTin/openwrt-mcp by Ian Williams, which targets GL.iNet firmware 4.x (OpenWrt 21.02, opkg). This is a port to stock OpenWrt 25.12 (apk, fw4/nftables, procd, netifd, LuCI JS). The security core is upstream's; see Credits for what came from where.

Requirements

  • Router: stock OpenWrt 25.12 (apk) or 24.10 (opkg), both with fw4/nftables. Nothing to install on the router beforehand. The package tools pick the manager from the binaries on the router (apk first, then opkg); system_status says which one and which firewall it found.

    • What differs on 24.10: pkg_query has no policy and no audit (opkg has neither; the tool says so). pkg_change simulates with opkg --noaction. New package defaults arrive as <file>-opkg instead of <file>.apk-new, and pkg_config_diff / pkg_config_resolve handle both (the old copy is kept as .pre-opkg-new; for /etc/config/NAME as the hidden .NAME.pre-opkg-new, which reload_config skips). Adding or removing a WireGuard peer re-runs ifup for the interface (24.10's handler cannot sync peers in place), so every tunnel's sessions restart for a moment. world lists the packages opkg marks "user installed". system_status mode=doctor reports opkg-new-pending; mode=audit skips the package audit and says why.

    • fw3 (OpenWrt 21.02 and older, or firmware built on it): best effort. firewall_show answers ruleset (iptables-save, IPv4) and rendered (fw3 -q print); check, table and chain are refused; a firewall apply is not pre-checked.

    • Tested on: 25.12.5 on a GL-MT6000 (hardware); the unit tests run both managers on fakes; CI runs the package and uci tools in the openwrt/rootfs container of 24.10 and 25.12 (no ubus or netifd there, so network, wireless and firewall paths are not covered). Firmware derived from OpenWrt (GL.iNet, ImmortalWrt) is best effort.

  • Your PC: OpenSSH (Windows 10 and later, macOS and Linux have it). Installing from a release needs nothing else. Building from source needs Go 1.26+, ssh and tar (Linux, macOS, or Git Bash on Windows).

  • Any CPU OpenWrt and Go share: the release has a binary for each (arm64, armv5/v7, mips/mipsle softfloat, mips64/mips64le, x86, x86-64, riscv64); install.sh reads the router's DISTRIB_ARCH and picks it, or cross-compiles when you build from source.

Tested on a GL.iNet GL-MT6000 (mediatek/filogic, aarch64_cortex-a53) with OpenWrt 25.12.5. Nothing in the code is specific to that board.


Related MCP server: ax11000-mcp

How it differs from other OpenWrt MCP servers

From each project's own README on 2026-10-07; "not stated" means the README does not say. Corrections are welcome.

this project

openwrt_ssh_mcp

paulomac1000/openwrt-mcp

openwrt-luci-mcp

Runs on

the router

a PC, in Docker

a PC, in Docker or Python

a PC, in Node.js

Reaches the router by

SSH to a key-bound forced command, or loopback HTTP

SSH

SSH

LuCI's HTTP /ubus

Changes configuration

yes, through one tool that checks first and arms a rollback

yes, including packages and a firmware flash

read-only unless ENABLE_WRITE_OPERATIONS=1

no

Automatic rollback of a bad change

yes, and it survives a reboot

not stated

not stated

not applicable

Access control and audit

per-client grants with scopes, expiry and a rate limit, audit log, optional TOTP

command whitelist, audit log

audit log

secrets hidden, no audit log

Package manager

apk (25.12) or opkg (24.10)

opkg

opkg

lists installed and available

Flashing firmware

never

yes

not stated

no

Needs on the router

the binary

SSH

SSH

uhttpd-mod-ubus, rpcd


What changed from upstream

upstream 0.5 (21.02 / GL.iNet)

this port (25.12)

Packaging

.ipk for opkg

install.sh file install + keep.d (25.12's apk has no mkpkg; see below)

Web UI

GL.iNet oui-httpd page

LuCI page, Services -> MCP Server: status, and approve or deny requests

Transport

HTTP over an ssh -L tunnel

same, plus stdio over SSH via a key-bound forced command -- no tunnel to keep alive

Rollback snapshot

/tmp (lost on reboot)

on flash; an unconfirmed change is rolled back at the next start, including after a power cycle

uci_apply

set / create / delete

+ add_list, del_list, set_list, dry_run, shows the staged uci changes, strict name validation. A dry run ends with advice, warnings from this change.

Reload

ubus call uci reload_config (async)

/sbin/reload_config, plus explicit config.change events when it has no checksums (first run after boot)

WireGuard

GL wireguard_server / gl_ddns

stock network.<iface> + wireguard_<iface> peers, DDNS from ddns, CGNAT warning, PSK, list and remove

Packages

--

pkg_query, pkg_change (simulate first), .apk-new review with a settings-level diff

Firewall

--

firewall_show: nft ruleset, fw4 print, fw4 check

Services

--

service_list / service_control via rpcd rc

Scope globs

[0] was a character class

brackets are literal: firewall.@rule[3].* means what it says

Presets

--

`openwrt-mcp allow @readonly


Tools

Tool

Scope

system_status

tool

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, conntrack and storage nearly full, pending .apk-new, NTP or an unset clock, a newer kernel installed than running). `history=1h

logread

tool

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 a token; baseline=<token> shows only the messages that were not in the log then. Baselines hold fingerprints, not log text, and live in memory.

network_clients

tool

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

tool

nft list ruleset, fw4 print, fw4 check, one table or chain.

net_diag

<action>[.<target>]

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 rates for a few seconds and ranks the conntrack table by source. usage reads nlbwmon's totals per device for an accounting period (a month by default). All three only read. throughput runs iperf3 against a server you name, 3 s up and 3 s down by default, 5 s each at most, and reports Mbit/s; capture runs tcpdump on one interface for at most 10 s or 2000 packets, with a filter of BPF primitives only, and returns a summary (protocols, top senders, TCP resets, DNS names asked), never the packets. Both need the binary installed and are not in @readonly or @operator: grant throughput.* and capture.* by name.

uci_get

<config>[.<section>[.<option>]]; refs for a name search

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

<config>.<section>[.<option>] per change; <config> for restore; probe.<kind>.<target> per probe

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 is read back; a change the router did not keep is NOT_APPLIED and nothing is reloaded.

uci_confirm / uci_rollback

tool

Make a pending change permanent / undo it now.

service_list / service_control

tool, <service>.detail / <service>.<action>

procd services; service_list detail=NAME returns an installed add-on's own status (tailscale, AdGuard Home, podkop, and the 1.7 wave: adblock, adblock-fast, banIP, ddns, https-dns-proxy, miniupnpd, mwan3, pbr, sqm, ttyd; 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 says if it did not; a final state that contradicts the action is NOT_APPLIED. Add-on verbs (`action=refresh

pkg_query

tool

installed, upgradable, search, info, files, owner, policy, apk audit, world; 200 lines a page, offset for the next.

pkg_change

<action>.<pkg> / upgrade

apk add/del/upgrade; simulates unless commit=true; reports new .apk-new files; checks /etc/apk/world afterwards.

pkg_config_diff

tool

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

live path

keep_current (drop the new default) or use_new (install it; rollback-armed for UCI configs).

sysupgrade

<action>

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

tool

Peers with handshake age, endpoint, traffic, config/kernel mismatch, duplicate names.

wg_new_client

wireguard.<iface>; wireguard.<iface>.reveal for reveal=true

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

wireguard.<iface>.<name>

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

(ungated)

Discovery: every object, method and argument signature.

ubus_call

<object>.<method>

Anything else on the bus. Replies over 8 KB have long arrays pruned.

exec

argv[0]

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

(ungated)

Opens the TOTP window for MFA-gated tools.

request_access

(ungated)

Opens one request per entry at once, without waiting, so the operator answers them together. Grants nothing.

Prompts. Clients that show MCP prompts (as slash commands, usually) get five recipes: router-health, who-is-online, secure-my-router, wifi-doctor and upgrade-plan. Each is a few lines that name the tools to call and end in a report or a proposal, never a change. They use only what the @readonly preset grants, so a read-only client can follow them to the end, and they cost nothing until used. Listing or fetching one runs nothing on the router, so no policy applies and nothing is audited.


Warnings, references, peers and add-ons

Warnings in a dry run. uci_apply dry_run ends with warnings from this change: findings the change would add that the router does not have today, ranked like the audit's, each with a next step and an OpenWrt wiki page. They are advice, never a refusal. They cover a port or port forward opened to the internet, WAN zone input or forward set to ACCEPT, SSH password logins switched on, an SSID left without encryption, a name a change removes or misspells while other sections still use it (ref-removed, ref-unknown, with a "did you mean" for a case mismatch), and a change that turns off the Wi-Fi network your own session is connected through (radio-in-use). Something already wrong before the change is not reported again. A real apply does not repeat them, so run the dry run first.

The management path follows your session. Besides the LAN, its bridge, the SSH listener and the zone and rule for SSH, the interface your own SSH connection arrives through counts as the management path (the daemon resolves the client address with ip route get), so changes to a WireGuard tunnel you are connected over need a probe or force=true like changes to the LAN.

Before you rename or delete an interface, zone or device. uci_get refs=lan lists what defines the name (a network interface, a firewall zone, a device, a radio, an mwan3 member or policy) and every reference field that uses it: zone network, rule/forwarding/redirect src and dest, dhcp interface, wireless network and device, network device, ports, route.interface, sqm and mwan3 when installed. "defined as: nothing" means no section has that name (a typo or a case mismatch). Only these fields are read, so the search cannot be used to look for a key. It needs the scope refs, which @readonly and @operator include; config=firewall narrows it to one config.

Adding and removing WireGuard peers is a normal, rollback-armed change. The peer is written to /etc/config/network and netifd loads it, so other peers' sessions stay up. Both tools wait for the peer to appear on (or leave) the running interface and say what they verified. Nothing is permanent until uci_confirm: otherwise, after the timeout or a restart, the peer is taken out again and a new client's key file is deleted. Only one change can wait for confirmation at a time. Removing the peer your own session arrives through needs force=true.

Add-on status. service_list detail=NAME reads an add-on that is installed (its init script exists) and prints a fixed set of fields, read-only: it never echoes a config file or a command's raw output, because those hold login hashes, proxy links, node keys and tokens. A grant needs the service's scope (tailscale.detail, or * as in @readonly); the plain list needs none. Text that someone else chose, such as a tailnet peer's host name, is clipped, sanitised and marked untrusted.

Add-on

What it reports

Verified

tailscale

state, tailnet DNS suffix, this node's addresses, advertised routes, exit node, health, peers (online, direct or relayed, traffic)

GL-MT6000, 25.12

AdGuard Home

running, listen addresses, protection and filtering switches, upstreams (scheme and host only), bootstrap, filter list and rule counts, whether dnsmasq forwards to it

GL-MT6000, 25.12

podkop

version, sing-box running, nft table, dnsmasq path, settings, one line per section (type, interface, community lists, size of dynamic lists)

GL-MT6000, 25.12

adblock

query=<domain>: blocked by the merged list, or allowlisted. Status: procd instance, status, version, blocked domain count, active feeds, DNS backend, last run (from /var/run/adb_runtime.json)

after a real run on 24.10.8 (VM, adblock 4.4.2-r4, 187,749 domains), status and query

adblock-fast

query=<domain>: blocked by which list, or allowlisted. Status: procd service data: status, the package's stats line, error and warning codes (not their info text), config summary

24.10.8 and 25.12.6 (VMs, adblock-fast 1.2.4-r4): failed, running with 239,581 domains, query

banIP

query=<ip>: which active sets hold it. Status: version, element count, active feeds, WAN interfaces (warns when none), last run

24.10.8 (banip 1.5.6-r7) and 25.12.6 (1.9.1) VMs: disabled, running, query, unban

ddns

service_control action=update clears the last-update record and restarts the updaters. Per section: domain, provider, registered address, WAN address from netifd, age of the last update; warns on a stale record and on a WAN address in 100.64.0.0/10

24.10.8 (VM, ddns-scripts 2.8.2): stock config and a real update

unbound

running, listen port, DHCP link, DNSSEC validator, recursive or forwarding, cache statistics when unbound-control works, whether dnsmasq forwards to it

24.10.8 and 25.12.6 VMs at stock config

stubby

listen addresses, upstream hosts with their TLS names (pinsets never printed), whether dnsmasq forwards to it

24.10.8 and 25.12.6 (stubby 0.4.3) VMs at stock config

smartdns

listen port, redirect mode, upstream servers as host only, whether dnsmasq forwards to it

24.10.8 and 25.12.6 VMs at stock config

watchcat, nextdns, qosify, travelmate, zerotier, netbird

rules, profile set or not, interfaces and classes, travelmate's status, uplink in use (SSID untrusted) and its subnet clash or failed internet check, networks and addresses, management and peer counts; no keys, ids or names

24.10.8 and 25.12.6 VMs at stock config (25.12: watchcat 1, qosify 2024.09.20): installed, not connected to a peer or a login; zerotier 1.16.2 (25.12) joined to a private network (OK, ACCESS_DENIED) and to one that answers NOT_FOUND; netbird 0.82.0 status as a connected cloud peer (taken from a container: the 0.59.13 feed package failed to dial on the 24.10 VM); travelmate (2.2.1 and 2.4.9) associated to a virtual access point

openvpn

instances and role; for an enabled instance the status file the init script asks for: connected clients (name, virtual address, traffic, since; never the client's public address) on a server, tunnel counters on a client

25.12.6 VM, OpenVPN 2.7.8: a TLS server with a client connected from a namespace; the client-mode file from the same build

ipsec/swanctl (strongSwan)

IKE and child SA counts; per SA its state, age, child state and traffic (no addresses; peer ids are marked as the peer's); a configured connection with no SA now

25.12.6 VM, strongSwan 6.0.7: two charon daemons in network namespaces, PSK, IKEv2, listing from the responder; idle with one connection loaded

cloudflared, frpc, frps, collectd

token and password set or not, server and proxy list (type, local port, remote port, never the token), data directory (RAM or flash) and enabled plugins; system_status history= reads the RRD files

collectd on GL-MT6000 (status); history on a 25.12.6 VM with luci-app-statistics and rrdtool 1.0.50, a few minutes of data (25.12; collectd 5.12.0); cloudflared on 24.10.8 and 25.12.6 VMs at stock config; frpc and frps (0.66.0) on the 25.12.6 VM at stock config, where the section is common, no connection between them

samba4, ksmbd, transmission, aria2, minidlna, mosquitto, tor, acme, nut-monitor

shares and guest access, RPC bind and auth, listeners and anonymous access, Tor ports, certificate days left, UPS status; secrets only as set or not

samba4 on GL-MT6000 (25.12) and on the 25.12.6 VM with a real login; tor on GL-MT6000 and VMs; ksmbd, transmission, aria2, minidlna, mosquitto, acme on 24.10.8 and 25.12.6 VMs at stock config; nut-monitor fixture-tested

wifischedule, vnstat, hd-idle, keepalived, lldpd, nlbwmon

schedules, tracked interfaces, disks and idle timers, VRRP config (not live state), ports with a neighbour, database path and whether it is in RAM

nlbwmon and lldpd on GL-MT6000 (25.12); the others on 24.10.8 and 25.12.6 VMs at stock config

OpenClash

best effort: clash process, mode, subscription count, dashboard secret set or not; no node names, links or secrets

luci-app-openclash 0.48.002 (project apk or ipk) with mihomo as its core on the 25.12.6 and 24.10.8 VMs, running with a local profile; its rules live in inet fw4

zapret

best effort: nfqws/tpws running, nft table zapret loaded

zapret v72.13 (project openwrt-embedded bundle, x86_64 binaries) on the 25.12.6 and 24.10.8 VMs, nfqws mode running

v2rayA

best effort: process, enabled flag, API address

v2rayA from the official feeds, running with the stock config on 24.10.8 (2.2.7.3) and 25.12.6

passwall, passwall2

best effort: xray or sing-box running, nft table loaded, enabled flag, DNS mode (passwall) or remote DNS protocol (passwall2), node and shunt-rule counts; no node names or links

passwall and passwall2 26.11.3: the stock config layout read on the 25.12.6 and 24.10.8 VMs (unpacked, never started: their dependencies are not in the official feeds)

nikki

best effort: mihomo running, nft table nikki, enabled flag, TCP mode, subscription count

nikki 2026.10.10 with mihomo-meta 1.19.32 (project apk or ipk) on the 25.12.6 and 24.10.8 VMs, running; real traffic sent through a proxy rule on 25.12.6

homeproxy

best effort: sing-box running, routing mode, DNS strategy, node count, the last error lines of homeproxy's log when it stopped (marked untrusted)

luci-app-homeproxy on the 24.10.8 VM (26.187, sing-box 1.12.22): running; on the 25.12.6 VM (26.298, sing-box 1.13.21) it does not start, and the detail shows why

youtubeUnblock

best effort: process, its chain in inet fw4, config strategy, queue number, packet mark, profile count; no domain lists

youtubeUnblock 1.3.1 (project apk or ipk) on the 25.12.6 and 24.10.8 VMs, running

https-dns-proxy

instances: resolver host only (no path, so no NextDNS id), listen address and port, bootstrap set or not; whether dnsmasq forwards to a local proxy port

24.10.8 and 25.12.6 (VMs, 25.12: 2026.05.06), running with two instances

miniupnpd

settings (warns when secure mode is off) and the live mappings: protocol, external port, client, description (marked untrusted); service_control action=unmap arg=tcp:PORT removes one

24.10.8 (VM, 2.3.9): a real mapping made with upnpc; 25.12.6: a mapping from a LAN client in a namespace and unmap on it (the mapping gone from the lease file and the rules, the others kept)

mwan3

per interface: status, link, tracking state, track IPs up, time online; per policy: members and weights, warns when no member is online (from ubus call mwan3 status). query=<ip>: the first rule whose dest_ip or src_ip holds it, its policy and the policy's members now

24.10.8 (VM, mwan3 2.11.16-r5), stock config

pbr

gateways with routing table, fwmark and priority, error and warning codes, settings incl. firewall mask, policy names and interfaces (not their addresses or domains); policies whose interface has no gateway are marked. query=<ip>: the policies whose src_addr or dest_addr hold it, and their interface

24.10.8 and 25.12.6 (VMs, pbr 1.2.2-r20): a policy that built nft rules, and one pbr rejected; 25.12.6 with a second uplink (wan2): its gateway, routing table, fwmark and rule priority as pbr built them (packets were not forwarded through it)

usteer (2025.10.04)

policies on and off (band steering, load balancing, roaming, minimum-SNR kick), the interface it exchanges state over, local nodes, how many other usteer hosts and clients it sees; no client addresses

25.12.6 VM idle (no access point, no peer); 24.10.8 VM with a real radio (RTL8852BE passed through), one 5 GHz AP and a phone associated; with a second host (the 25.12.6 VM, a virtual hwsim AP) seen from the 24.10.8 side only

DAWN (2025.11.07)

AP discovery mode, whether traffic between APs is encrypted (warns on the shipped key; keys never printed), hostapd interfaces on ubus, entries in the network view and hearing map

25.12.6 VM idle; 24.10.8 VM with a real radio, one AP and a phone associated; a second AP (25.12.6 VM, hwsim) shows in the network view of the 24.10.8 side only

openNDS

version, uptime, managed interface, clients now and authenticated since start, FAS level and host (not its path), idle timeouts, binauth script; the FAS key only as set

25.12.6 VM (10.3.1), no clients

sqm

per queue: interface, rates, qdisc, script, live packets, drops and backlog from tc -s; warns when flow offloading bypasses the shaper

24.10.8 (VM)

ttyd

per instance: port, interface (warns when it listens on every interface), whether a credential is set (never its value), TLS, read-only

GL-MT6000, 25.12

"Fixture-tested" means the parser is tested against inputs written from the add-on's upstream source (its init script, rpcd plugin or runtime file), not against a capture from a router. "Source-checked" adds one step: option, process and nft table names were compared with the project's own default config and init script at the version shown. Everything else was run on a real OpenWrt (ROADMAP 9.7; the captures are in testdata/captured/): the GL-MT6000 (25.12.6, read-only), and 24.10.8 (opkg) and 25.12.6 (apk) x86 VMs. "Stock config" means installed and started with the package's default settings, so a state that needs a peer or a login (a connected VPN, a travelmate uplink, an SMB login) is not covered. The wave 4 proxy adapters other than podkop are not in the official feed: they are checked against each project's own default config and init scripts (named in the table), not run on a router.

Deliberately not read: AdGuard Home's web API (it needs the UI login), podkop's proxy_string, selector and outbound settings, and the user's domain and subnet lists.

Install

On the router, from a release (nothing needed beyond a default 25.12 image):

wget -O /tmp/install-router.sh https://github.com/stanislav-testhub/openwrt-mcp/releases/latest/download/install-router.sh
sh /tmp/install-router.sh

It picks the archive for the router's DISTRIB_ARCH, checks it against the release's SHA256SUMS (refusing on a mismatch), and installs. VERSION=v1.2.0 selects a release other than the latest. Each release file also carries a build attestation: gh attestation verify <file> --repo stanislav-testhub/openwrt-mcp.

From a PC, building from source (needs Go, ssh and tar; Git Bash works on Windows):

git clone https://github.com/stanislav-testhub/openwrt-mcp
cd openwrt-mcp
ROUTER=root@192.168.1.1 SSH_PORT=22 SSH_KEY=~/.ssh/id_ed25519 ./install.sh install

ROUTER, SSH_PORT and SSH_KEY are your router's root login (defaults: root@192.168.1.1, 22, your ssh defaults). ./install.sh install --release [vX.Y.Z] skips the build and has the router fetch a verified release instead; that is also what happens when no Go toolchain is found.

Either way the same installer runs on the router.

  • It installs:

    • /usr/bin/openwrt-mcp;

    • the init script;

    • the default config, never overwriting an existing one;

    • the keep.d entry;

    • the LuCI page.

  • It then enables and starts the service.

  • It refuses to restart the daemon while a uci_apply awaits confirmation, because that would roll it back, unless FORCE=1.

  • It checks that the binary fits on the overlay first.

./install.sh uninstall [--purge] reverses it.

Approve from LuCI

After install, Services -> MCP Server in LuCI shows the daemon (running or stopped, version, HTTP listener, stdio socket), a pending uci_apply with its automatic-rollback deadline, the paired HTTP clients, the standing policies and the audit log. It is also where you answer an agent, so nobody has to open a shell to paste an allow line.

  1. The agent calls a tool it has no grant for. The call is refused and a request is recorded: client, tool, the exact scope that failed and the redacted arguments, all derived by the daemon, with no text from the agent.

  2. The request shows at the top of the MCP page and in a widget on Status -> Overview, which appears only while something is pending.

  3. Allow writes a grant, Deny refuses it. The default grant is the narrowest one (this tool on this exact scope, 1 hour). A select widens it (the scope's family, every scope, the @operator preset) and sets 15 minutes to 7 days. A request for a root-shell tool shows a warning and needs a second confirmation.

  4. With option request_wait '300' (seconds, 0 to 600, default 300; 0 refuses at once) the denied call is held and continues by itself when a grant covers it, so the agent does not retry. Without it, or when the wait runs out, the agent gets POLICY_DENIED with the request id, and a retry after approval works. The allow line is still printed, and the CLI releases a held call the same way the button does.

Requests are deduplicated, capped (5 open per client, 50 in all) and expire after request_ttl (10 minutes by default). They live in RAM, so a reboot clears them. A LuCI user with only the read ACL sees requests but no buttons; writes need luci-app-openwrt-mcp-write.

Other tabs: Permissions (presets, tools in groups with a risk badge, Revoke), Activity (the audit log with filters), Settings (request wait and TTL, the optional channels, second-factor state).

Permit all. The Permissions tab ends with a red section that grants a client every tool on every scope, exec included: a root shell. It is capped at 24 hours (no "never"), needs a checkbox and the client's name typed in, is refused for a client with a second factor enrolled, and shows a red banner on both pages with End now while it lasts. Calls it authorises are marked "via":"permit-all" in the audit log. The CLI equivalent is openwrt-mcp allow <client> @all 1h --shell-equivalent. Prefer approving requests one by one.

Optional channels are off after install; each is a switch on Settings, with a notice beside it saying how it can harm you, and each switch is audited.

Channel

Option

What it does

How it can harm you

Pair from LuCI

pairing

A Clients tab: paste the key that openwrt-mcp connect prints, name the client, pick a starting preset (Read-only by default). Writes the same forced-command line as authorize-key.

Anyone with LuCI write access can add a key that reaches the router over SSH.

Push hook

push_hook

Each new request fires the ubus event openwrt-mcp.request and runs the executables in /etc/openwrt-mcp/hooks.d/ with the redacted request as JSON on stdin (10 s limit; group- or world-writable, non-executable and dot files are skipped). For Telegram, ntfy or Home Assistant; examples/hooks/telegram and examples/hooks/ntfy are ready to copy, with credentials read from UCI. A notification does not approve; it points at LuCI.

Request details leave the router, and a hook runs as root.

Approve in chat

chat_approve, list chat_approve_client

A client that negotiates elicitation also shows the request in its own prompt. Exact scope only, 15 minutes, 1 hour or 8 hours, never for a root-shell tool or Permit all.

The client relays your answer. A client or agent that auto-answers prompts would grant itself.

What an agent cannot do. A LuCI administrator is already root, so a button gives no person more power. What must not happen is an agent widening its own grant, so a built-in deny floor refuses, whatever the grant (@operator and @all included): ubus_call to the objects openwrt-mcp, session, file and rpc-sys and uci writes to the openwrt-mcp and rpcd configs; exec of the binary and its rpcd plugin, or on the policy, the rpcd config, /etc/openwrt-mcp and the request state; and uci_apply, history restore and pkg_config_resolve on those two configs. A client that already holds a root shell is outside what the floor can claim: see SECURITY.md. Design note: docs/luci-approvals.md.

Run on a real OpenWrt 25.12.5 router (including the LuCI phone layout) and on a 24.10.8 VM: the LuCI pages rendered in headless Chromium, the approve, deny and root-shell confirmation flow, rpcd refusing a write call for a read-only login, and the Overview widget showing only while a request is pending. Screenshots will be added.

Why not an .apk: 25.12 packages are apk-tools v3 ADB archives. Building one needs the OpenWrt SDK or a host apk-tools with mkpkg (the router's apk has no mkpkg), and an unsigned package then needs --allow-untrusted anyway. A static binary loses nothing by being installed as files: /etc/config survives sysupgrade on its own, and /lib/upgrade/keep.d/openwrt-mcp carries the binary, init script, rc.d links, state and LuCI page. (An owut/ASU image rebuilds packages, not loose files -- the keep.d entry is what preserves this across one.)


Connect

openwrt-mcp connect (recommended)

The release has a binary for your PC too (openwrt-mcp_<version>_windows_amd64.zip, darwin_arm64.tar.gz and so on; a Linux PC can use the linux_ archive). Unpack it anywhere on your PATH; it needs OpenSSH, which Windows 10 and later, macOS and Linux have. Then, on your PC:

openwrt-mcp connect --client claude-code --host 192.168.1.1          # or claude-desktop, codex, cursor, gemini, vscode

It makes a dedicated ed25519 key (~/.ssh/openwrt_mcp, never overwriting one), prints the two commands to run on the router once, and shows the entry to add to your client. Add --write and it does that last step: for Claude Code and Codex by running their own mcp add, for Claude Desktop, Cursor, Gemini CLI and VS Code by merging one openwrt entry into their JSON file (other servers stay; the original is kept once as <file>.before-openwrt-mcp; a file with comments is left alone and the snippet printed instead). The entry stores ssh and its arguments as a list, so spaces in a key path need no quoting, and it sets keep-alives so a router that rebooted is noticed.

openwrt-mcp connect doctor --host 192.168.1.1

checks the chain in order and stops at the first break, with one fix for it:

[ ok ] ssh reachable   192.168.1.1:22
[ ok ] host key
[ ok ] key accepted    /home/you/.ssh/openwrt_mcp
[FAIL] forced command  the key logged in, but nothing answered as an MCP server (...)
       fix: the key is probably authorized without its forced command ...
[skip] daemon socket

The steps are: SSH reachable, host key, key accepted, forced command, daemon socket, initialize, tools/list. Wrong key, a missing forced command, a stopped daemon and a disabled socket each name their own step.

After a reboot or a daemon restart. A reboot, an install.sh upgrade or a crash ends every open session: the openwrt-mcp stdio bridge exits with daemon closed the connection, and the client shows the server as disconnected. MCP clients do not all reconnect by themselves, so reconnect from the client (its MCP menu, or restart the client). SSH answers a few seconds before the daemon is listening after a boot; the bridge waits up to 10 seconds for the daemon's socket before it fails with daemon not reachable ... after waiting 10s (and [code: TIMEOUT; ...]), so a reconnect right after the router comes back normally just works, and if it does not, wait a few seconds and reconnect again. A change that was still waiting for uci_confirm is rolled back at the next start. openwrt-mcp status shows the last disconnect and why (client closed the connection, connection error: ..., or the daemon restarted (router reboot, upgrade or crash)), read from the audit log, which also carries one stdio session closed after ... line per session and one daemon started line per start.

Narrower sessions, and the shell

Ask for less than the key allows. The policy decides what a client may do; a client can also ask for less for one session.

openwrt-mcp connect --client claude-code --host 192.168.1.1 --read-only            # nothing that changes the router
openwrt-mcp connect --client claude-code --host 192.168.1.1 --toolset diag,pkg      # only those tools

Toolsets are diag (logread, network_clients, firewall_show, net_diag, service_list, ubus_list, ubus_call), config (uci_get, uci_apply, uci_confirm, uci_rollback, service_control), pkg (pkg_query, pkg_change, pkg_config_diff, pkg_config_resolve, sysupgrade) and wg (the three WireGuard tools). system_status is always there; exec is in no toolset. --read-only is the @readonly preset intersected with the client's grants, so it can only remove things, and a hidden tool is refused when called, not just left out of the list. The profile travels as words after the forced command (SSH_ORIGINAL_COMMAND), which the daemon parses against a fixed grammar: anything else is refused and audited, and there is no word in it that widens a session.

From a shell or a script, no MCP client. The same SSH key runs one tool at a time:

ssh -T root@192.168.1.1 call --list
ssh -T root@192.168.1.1 call uci_get --help
ssh -T root@192.168.1.1 call uci_get '{"config":"network"}'
ssh -T root@192.168.1.1 -- --read-only call uci_get '{"config":"network"}'   # after a profile word, `--` ends ssh's own options

The result is text on stdout; a refusal or error goes to stderr with the allow line and exit status 1. The call runs through the same policy, audit and redaction as an MCP session. skills/openwrt-mcp/SKILL.md is a ready-made skill file for agents that prefer a shell to MCP.

Limits. Each tool has a deadline above its own waits, and at most 8 calls run at once: the rest wait up to 30 s and then get a busy refusal (TIMEOUT). A client that cancels a call kills the command it started. uci_confirm, uci_rollback and mfa_unlock never wait for a slot.

stdio over SSH, by hand

A dedicated key, bound on the router to the MCP bridge and nothing else:

ssh-keygen -t ed25519 -N '' -f ~/.ssh/openwrt_mcp
ssh root@router "openwrt-mcp authorize-key claude-code '$(cat ~/.ssh/openwrt_mcp.pub)'"
ssh root@router "openwrt-mcp allow claude-code @readonly 30d"
claude mcp add openwrt -- ssh -T -i ~/.ssh/openwrt_mcp -o BatchMode=yes root@router

authorize-key writes a line like command="/usr/bin/openwrt-mcp stdio --client claude-code",no-port-forwarding,no-agent-forwarding,no-X11-forwarding,no-pty ssh-ed25519 ... into /etc/dropbear/authorized_keys: that key gets the MCP server as client claude-code and cannot open a shell or forward ports. It refuses a key that is already a root login.

The bridge pipes the session into a root-only unix socket (/var/run/openwrt-mcp/mcp.sock, 0600 in a 0700 directory). The daemon runs the tools, so a rollback armed in one session outlives it. The client name on the socket is asserted, not proven -- sound because only root can connect, and root can already edit the policy file; the SSH key is the real authentication.

On Windows, the built-in OpenSSH client works for this (ssh.exe); use a full path to the key.

HTTP over a tunnel

Unchanged from upstream: openwrt-mcp pair <client> prints a bearer token once; ssh -N -L 8730:127.0.0.1:8730 root@router; then claude mcp add --transport http openwrt http://127.0.0.1:8730/mcp --header "Authorization: Bearer $TOK". The daemon refuses to bind anything but loopback.

Make the policy mean something

If the agent can also run ssh root@router ... through its shell tool, the policy is advisory. Deny that in the client (Claude Code: a permissions.deny rule for Bash(ssh * root@<router>*)), or keep the root key where the agent cannot read it.


Policies

Deny by default. A policy grants one client a list of tools, scope globs (* and ? are wildcards; brackets are literal), a calls/minute ceiling and an expiry. Changes to /etc/config/openwrt-mcp take effect without a restart.

openwrt-mcp allow claude-code @readonly 30d          # every read tool; ubus_call on an allow-list of read methods
openwrt-mcp allow claude-code @operator 7d           # + uci_apply/confirm/rollback, service_control, pkg_change,
                                                      #   pkg_config_resolve, wg_new/remove_client, sysupgrade backup
openwrt-mcp allow claude-code uci_apply 'dhcp.* wireless.*.disabled' 30d
openwrt-mcp allow claude-code service_control 'dnsmasq.restart adguardhome.*' 30d
openwrt-mcp revoke claude-code                        # remove every policy for the client
openwrt-mcp prune --older-than 7d                     # delete grants that expired over a week ago (audited)
openwrt-mcp policies | status [--all] | clients

Granting the same tools and scopes again replaces the client's expired grant instead of adding a block. status counts expired grants in one line; --all lists them.

Neither preset includes exec or unrestricted ubus_call; both bypass the safety rails. The read-only ubus list is explicit object.method pairs, not *.list-style globs, because session.list returns LuCI session ids. uci_get '*' reads every config, but the values of secret options (Wi-Fi keys, WireGuard keys, passwords, tokens) come back as <redacted>; see Safety model. exec is not masked.

A refusal names the uncovered scope and prints the exact allow line that would cover it.

An exec scope is argv[0] taken literally, so a grant for find or awk looks harmless and is a root shell: both run other programs, and so do the shells, env, nice, flock, timeout, xargs, tar, ssh, lua, ucode, apk and opkg. allow refuses such a grant until you add --shell-equivalent, judging by base name so /usr/bin/../bin/sh and /bin/* count too; a ubus_call grant that can reach file.exec is treated the same way. openwrt-mcp policies and status mark these grants, which also covers a policy written by hand. The list is a floor, not a promise: a grant that writes files (wget, cp, dd) or starts an interpreter that is not on it can still be abused.

Second factor

Unchanged from upstream: openwrt-mcp mfa enrol <client> prints an otpauth:// URI; then in a policy list mfa_tools 'uci_apply', option mfa_window '15m'. One code opens a time-boxed window; codes are single-use; unlocks live in memory only.

Enrolling alone gates nothing. Only a config policy section in /etc/config/openwrt-mcp with mfa_tools is gated, and mfa_tools may name only tools that same policy grants. Grants made with openwrt-mcp allow or from the LuCI page never require a code. openwrt-mcp mfa status says when an enrolled client has no gating policy.

Wrong codes are limited: in the config server section, option mfa_max_failures '5' consecutive wrong codes lock that client out of mfa_unlock for option mfa_lockout '300' seconds ('5m' also works), doubling on each repeat to one hour. A correct code during the lockout is refused and not spent. A client with no secret counts the same, so the limit reveals nothing about enrolment, and the counters are in memory (a restart, mfa enrol or a rotated secret clears them). Each wrong code is audited as ERROR and a lockout as DENIED; the code itself is never logged. The price: whoever holds a client's token can keep that client locked out for up to an hour.


Safety model

  • Rollback that survives the thing most likely to happen. uci_apply snapshots the touched configs to /etc/openwrt-mcp/rollback/<token>/ (fsynced), writes the pending record before committing, commits, reloads, and arms a timer (default 90 s, max 600 s). No uci_confirm -> files restored atomically, staged changes reverted, services reloaded. If the router is power-cycled inside the window, procd starts the daemon after network (S95) and it rolls back at startup, forcing a config.change for each restored config.

  • Nobody else's edits. Every committing tool refuses to run while the configs it would commit have uncommitted changes from another session, and while an unconfirmed apply is pending.

  • Checked before it reloads. The dry run runs each service's own checker on the staged config where one exists (fw4 check for the firewall) and lists only the problems the change adds. A real apply refuses them unless force=true; a config that was already broken can still be fixed. dnsmasq, dropbear and the rest have no checker that sees staged changes: they are reported "not checked", not "passed".

  • Read back after it writes. uci_apply re-reads each config after the commit and before any reload; wg_new_client, wg_remove_client and pkg_change look at the peer table, the config and /etc/apk/world afterwards; service_control compares the final state with the action. A write the router accepted and did not keep is NOT_APPLIED, with the rollback still armed for uci_apply. A read-back that cannot run says "Not verified". Positional sections (@rule[3]) cannot be compared and are counted.

  • No silent overwrite. uci_get ends with the config's revision. Pass it back as expected_revisions and the apply is refused with CONFLICT if the config changed meanwhile (LuCI, another client).

  • The management path is guarded. A change to the LAN interface or its bridge, the SSH listener, or the firewall zone and rule that let SSH in is refused unless the call names a probe (ping the gateway, resolve a name) or force=true. Probes run after the reload and are reported with the result; the rollback window defaults to 180 s for such a change. The rule set is static (LAN plus whatever dropbear names), so it covers the common layout, not every topology.

  • History and restore. Confirming a change keeps the version of the config from before it (newest history_keep, default 5, per config, in /etc/openwrt-mcp/history/). uci_get history=list shows them, history=diff:<id> compares one with now, and uci_apply restore=<id> puts one back through the same snapshot, checks and rollback timer. Entries contain secrets, like the snapshots: 0600, masked when shown, and part of a sysupgrade backup. option history_keep '0' turns it off.

  • No self-promotion. uci_apply and pkg_config_resolve refuse the openwrt-mcp policy config whatever the grant, so a client cannot write itself a wider policy. Policies change only through openwrt-mcp allow / revoke on the router.

  • @operator is powerful. uci_apply on * reaches every UCI config, including dropbear, rpcd and uhttpd, and pkg_change installs packages as root. Grant it for a working session (2h), and keep long-lived grants to narrow scopes such as 'dhcp.* wireless.*.disabled'.

  • Names are validated against UCI's grammar, so a section like lan.ipaddr=x cannot make uci act on a different key from the scope the policy approved.

  • No shell, anywhere. Every command is an argv; targets and names that could be read as options (-f) are refused.

  • Lifelines. service_control will not stop or disable dropbear, network, rpcd or openwrt-mcp. sysupgrade has no flash action -- validate an image with test, flash by hand. wg_remove_client will not drop a tunnel that handshook in the last 3 minutes, or the one this session arrives through, unless forced.

  • Credentials stay out of the conversation. wg_new_client writes the new client's config (private key included) to a root-only file in RAM, beside the socket, and returns the public key and the command to run. openwrt-mcp wg-show <name> on the router prints the config and a QR code in your terminal and deletes the file; an uncollected file goes after 24 hours or at the next reboot. Only reveal=true puts the key in the result, and so in the model's context and the provider's logs. A sysupgrade backup is created 0600 before anything is written to it and only the newest one is kept. The audit log records arguments and a summary, never tool output, and redacts secret-looking fields. The server private key is read from wg show dump and discarded.

  • Secrets are masked in tool output. uci_get, uci_apply (diff and errors), pkg_config_diff, pkg_config_resolve, uci_confirm, uci_rollback, system_status and ubus_call keep the shape of a line and replace the value of a secret option (key, key1..key4, psk, password, sae_password, passphrase, private_key, preshared_key, token, pwd, anything containing secret...) with <redacted>. The audit log uses the same rule. exec, logread and the diagnostics are not masked, and wg_new_client is exempt on purpose. In the config server section: list redact_extra 'vendor_blob' adds names; option redact_output '0' turns masking off, and is audited. A masked diff does not show what changed in a secret.

  • Router output is untrusted. Host names, SSIDs, log lines and DNS answers are chosen by other devices. Every result has terminal escape sequences, control characters, bidi and zero-width characters and invalid UTF-8 removed, and lines are cut at 1024 bytes (not exec, ubus_call, wg_new_client or the configuration tools). network_clients, logread and net_diag start with an [untrusted text: ...] line. That lowers the odds a model obeys such text; it does not remove them, so keep write scopes out of sessions that read it.

  • State stays off the web. The state directory, audit log and socket are refused if they sit under /www, a cgi-bin directory or uhttpd's home, even through a symlink.

  • A threat model is in SECURITY.md.

  • Upstream's findings still hold: rpcd ACLs do not bind a root process on the local ubus socket, so they are not relied on; rpcd's own apply/rollback keeps its state in rpcd memory and tmpfs, which is why the snapshot is ours and on flash.


Verified

On a GL-MT6000, stock OpenWrt 25.12.5, installed with install.sh's steps and driven from Windows exactly as Claude Code does (ssh.exe with a forced-command key, stdio bridge):

  • Install: procd service with respawn, S95/K10 links, socket 0600 in a 0700 directory, HTTP on 127.0.0.1 only, forced-command line in dropbear's authorized_keys, @readonly + time-limited @operator policies picked up without a restart.

  • Reads against live data: all 23 tools listed with schemas and server instructions; system_status, network_clients, wg_list_clients (duplicate-name warning), service_list, pkg_query upgradable, pkg_config_diff (11 real .apk-new files, settings-level diffs), firewall_show check, net_diag ping from br-WAN, logread filtering, uci_get, sysupgrade list, ubus_call.

  • Writes with rollback (on a scratch UCI config): uci_apply including set_list -> automatic rollback at the deadline, file restored byte-identical and pending.json removed; a second apply refused while one is pending; uci_confirm; uci_rollback on demand; dry_run.

  • WireGuard: wg_new_client with a preshared key (next free address, peer committed to UCI and hot-added to the kernel, CGNAT endpoint warning), listed, then wg_remove_client -- /etc/config/network back byte-identical, kernel peer gone. The 1.3.0 hand-over (second run, on an interface enabled for the test through uci_apply and disabled again afterwards, its config revision identical to before): the result carried no private key; the config was a root-only 0600 file in a 0700 directory under /var/run; openwrt-mcp wg-show, run from an operator terminal, printed the config and QR code and deleted the file. The 1.4.0 read-back printed Verified: ... for uci_apply, wg_new_client and wg_remove_client, each applied with the rollback armed and then confirmed.

  • Crash recovery: the daemon SIGKILLed with an unconfirmed apply -> procd respawned it after 6 s and it rolled the change back at startup.

  • Refusals: exec, ubus_call session.list, out-of-scope uci_apply (each naming the grant line), any uci_apply on the policy config, unauthenticated HTTP (audited).

  • Output safety (1.1.0), on the same board: uci_get wireless and ubus_call network.wireless status return <redacted> for every Wi-Fi key, while ssid, encryption and look-alike names such as wpa_disable_eapol_key_retries are untouched (numbers, booleans and arrays in the JSON reply too). A uci_apply dry run that sets a key shows it redacted and leaves nothing staged. network_clients and logread start with the untrusted-text marker. Five wrong mfa_unlock codes from a client with no secret lock it out for 5 minutes (the sixth is refused with a retry time); the audit log records four ERROR entries then DENIED, and none of the submitted codes appear in it. A syslog line written with ubus call log write that held CSI and OSC sequences, a colour code, BEL and a bidi override (all present in the router's own log) came back through logread with only the text and the tab left, and an over-long line was cut at 1024 bytes with a [+N bytes] note. The syntax of uci changes (+=, -=, '\'', a bare -path for a delete) was captured from the router and is a test fixture.

  • Reliable changes (1.2.0), on the same board, driven through the daemon's stdio bridge: fw4 check sees changes staged in uci (it exits 0 for an invalid value and prints [!] lines, which is what validation reads): a dry run that sets a bogus zone value reports it as a NEW problem, the real apply is refused, and nothing is left staged or snapshotted. A stale expected_revisions is a CONFLICT; the current one passes; one for a config the call does not change is refused. A dry run on the LAN interface names the management path, and a real apply without a probe is refused with nothing staged. add_list of an element already in system.ntp.server is skipped. On a scratch option in luci: an apply with a ping and a resolve probe reports both OK after the reload and arms the rollback; confirming it leaves a history entry (0700 directory, 0600 files); history=diff shows what the change added; restore brings the file back byte-identical with its mode, runs its probe, and leaves an entry of its own; an apply with a failing probe reports PROBE FAILED with the rollback still armed, and uci_rollback restores the file byte-identical. service_control restart of a daemon reports "Settled after" its state.

  • Adoption and credentials (1.3.0), on the same board: the build was installed with install.sh and openwrt-mcp version reported 1.3.0. connect doctor from the Windows PC, with its real OpenSSH, passed all seven steps and listed 23 tools; with a key the router does not know it stopped at key accepted, and with a closed port at ssh reachable, each with its fix. connect --write for Cursor made the key with the PC's own ssh-keygen, merged the entry into a JSON file, and a second run reported the entry unchanged. diag printed the version, board, policy shape and audit lines with the SSH client's address as ip-1 and no audit arguments; --detail added the masked summaries. sysupgrade backup created the archive -rw------- (4.3 MB, so sysupgrade -b keeps the mode of a file that already exists), and the second backup removed the first. The daemon held about 10 MB resident right after the restart.

  • Session cleanup (1.3.0), on the same board: after a daemon restart the stdio bridge started on the new build exited at once, and the client's next call opened a fresh session without an error; bridges still running the previous build stayed until their client's next request. status folded 45 expired grants into one line; prune removed them, wrote one prune audit entry, and the daemon reloaded with the live grants only.

  • Diagnose (1.4.0), on the same board, with a @readonly client: system_status mode=doctor listed one low finding, three .apk-new files waiting for a merge, which was true, and nothing that was not. mode=audit listed the firewall rule that lets the WireGuard port in from the WAN (true, and intended) and uhttpd listening on every address (true), with the wiki link and the next call for each. logread mode=summary folded a little over a thousand lines into about fifty distinct messages. A baseline saved, then compared after the periodic jobs had run, counted a monitoring line as new each time, because its uptime field changed; that is why durations became <dur>, and after the fix the same round trip reported nothing new. net_diag wifi_survey gave the busy, rx, tx and noise figures for the channel each radio was on, within a point of the raw iwinfo survey read earlier the same day; traffic sampled the interfaces for three seconds and ranked the conntrack sources by bytes; usage listed the devices from nlbwmon for the current monthly period; network_clients showed an AIR column whose shares added up to about 100% on each radio.

  • Reach and resilience (1.5.0), on the same board, 25.12.5: the build was deployed with the installer's steps. service_list detail= read tailscale, AdGuard Home and podkop. The dry-run warnings and the WireGuard writers ran on a throwaway interface made for the test (never the LAN, never the real tunnel), which was removed afterwards: a peer added and removed through the rollback-armed path and a rollback that put the peer back. openwrt-mcp call and a session with --toolset diag --read-only ran over SSH from the PC. The hardware run found a false NOT_APPLIED after removing a peer that was not the last one (UCI's anonymous section ids are positional, so the read-back looked at the wrong section); it is fixed, and the test fake now renumbers them the way UCI does.

Unit and end-to-end tests (real MCP client over in-memory transport and over the bridge handshake) run on any OS against a fake router: apply/confirm/rollback/timeout, restart inside the window, dry run, refusal on foreign staged edits, list ops, WireGuard add/list/remove against a captured 25.12 config, client join, log filtering, apk simulation, .apk-new resolution with rollback, preset contents, scope glob semantics.

Measured cost (sh bench/cost.sh, OpenWrt 24.10.8 in a virtual machine, 2026-11-04; calls, and bytes sent and received, not tokens; tokens are in the next paragraph). The same three tasks through openwrt-mcp and through raw ssh shell commands:

Task

openwrt-mcp

Raw ssh

Who is on my network (6 leases)

1 call, 17 sent, 1233 received

1 call, 35 sent, 949 received

Why is the second WAN down (DHCP gets no answer)

2 calls, 59 sent, 12219 received

3 calls, 75 sent, 3935 received

Add and remove a static lease

5 calls, 635 sent, 2018 received

2 calls, 303 sent, 83 received

On these tasks openwrt-mcp is not cheaper in bytes: the tool catalogue alone is 23866 bytes per session, and the lease task costs more because it dry-runs, arms a rollback and confirms. What the bytes buy is the policy check, redaction, the audit record and the automatic rollback, none of which a raw shell has. The WAN task is dominated by logread mode=summary over a log that holds a whole boot; it is the largest single reply and a candidate for trimming.

Tokens and tool choice (python3 bench/select_eval.py, DeepSeek deepseek-flash, 2026-11-05; the figures belong to that model and its tokenizer, not to Claude's). Each tool catalogue was given to the model with 29 plain requests ("who is connected", "install lldpd", "undo the change") at temperature 0, three runs each; the check is which tool the model calls first. The catalogue costs about 5.2 to 5.7 thousand prompt tokens per conversation (the figure includes a 100-token system prompt and the question):

Catalogue

Right tool first

Prompt tokens

1.2.0 (before the description trim)

74 of 87

5616

1.3.0 (after it)

78 of 87

5231

this version

76 of 87

5695

The trim did not make the choice worse. Most misses are the same on every version and are reasonable first steps rather than wrong tools: with no change pending in the conversation, the model reads the state before uci_confirm or uci_apply. The questions are synthetic and the set is small, so a gap of a few answers is noise.

Not yet verified on hardware (covered by the fake-router tests only): pkg_change with commit, the LuCI page rendering, the web-root guard on a real /www path or symlink, a real power cycle (the recovery path is the same one the SIGKILL test exercises), and keep.d across a real sysupgrade. For 1.2.0 also: history across a sysupgrade. A management-path change applied with a probe (then confirmed) and a probe failure left to the rollback timer (the timer restored the old value) were run on an OpenWrt 24.10.8 virtual machine (QEMU), not on hardware. For 1.3.0 also: connect --write against a real Claude Code, Codex, Claude Desktop, Gemini or VS Code (only the file merge and the command line are tested), anything on macOS, and the installer's download path on a router (the release workflow has run and published 1.2.0 and 1.3.0, but install-router.sh has not been run against them). For 1.4.0 also: the read-back after a write ran on hardware for uci_apply, wg_new_client and wg_remove_client only; service_control and pkg_change ran against the fake router, and the log summary has only seen the log of one router. The file modes of the WireGuard hand-over are asserted on Linux in CI. Reports from Reports from other boards are welcome.


Credits

  • GlassOnTin/openwrt-mcp (Ian Williams, MIT) -- the base of this project. Kept from it: the on-router static Go daemon under procd, standing deny-by-default policies with scope globs, rate limits and expiry, bearer tokens stored as digests, TOTP windows, the JSONL audit log with secret redaction, loopback-only HTTP, ubus reply pruning, and the confirm-or-roll-back idea for uci_apply. The git history of the upstream project is preserved in this repository.

  • jsebgiraldo/openwrt_ssh_mcp -- an off-router Python server (SSH per call, regex command whitelist), reviewed for ideas. Four were taken and reimplemented here:

    1. validating a firmware image before flashing (sysupgrade -T -> sysupgrade action test);

    2. firmware and board information (part of system_status);

    3. package management (rewritten for apk: pkg_query, pkg_change);

    4. ping / traceroute / nslookup (net_diag).

    Not taken: OpenThread border-router tools (hardware-specific), opkg and iptables commands (gone in 25.12), a flash-firmware tool (irreversible and unrecoverable remotely), and regex whitelisting of shell strings (argv + policy scopes instead).

Contributing and security

Bug reports and pull requests are welcome -- see CONTRIBUTING.md. Please report vulnerabilities privately as described in SECURITY.md, not in a public issue. Planned work is in ROADMAP.md.

Reporting a bug: on the router run openwrt-mcp diag and paste the output into the issue. It prints the version, board, daemon state, the shape of the policy and the last 20 audit lines (--audit N), with every IPv4, IPv6 and MAC address, host name, DHCP name, SSID, domain and WireGuard peer name replaced by a placeholder (ip-1, mac-1, host-1, ssid-1) that stays the same for the same value. Audit arguments are never printed, and the scope, summary and error text of an entry only with --detail, masked the same way. Names are matched against what the router itself says they are, so read it once before pasting: a name that is only in free text, not in the router's configuration, is not recognised.

Licence

MIT -- see LICENSE. Copyright (c) 2026 Ian Williams (upstream) and Stanislav Chupin (OpenWrt 25.12 port).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables Claude Code and other MCP clients to inspect and manage a TP-Link router over stdio, including device lists, DHCP leases and reservations, Wi-Fi settings, firmware and IP status, mesh nodes, and safe raw endpoint requests with confirmation for writes and secret masking.
      16
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude Desktop, Claude Code, and other MCP clients to manage firewall rules, VPNs, NAT, DNS, DHCP, routing, certificates, and diagnostics through natural language, with guardrails, rate limits, and config-revision backups that make destructive changes reversible.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude Desktop, Claude Code, and other MCP clients to manage a pfSense firewall through natural language — handling firewall rules, aliases, NAT, VPNs, routing, DNS, DHCP, certificates, users, services, logs, traffic shaping, and diagnostics across 332 API-verified tools. Every destructive change is guarded by confirmation prompts, rate limits, config-revision backup for rollback, and audit logging.
      -