keenetic-mcp
Summary: A Keenetic router MCP server for monitoring, diagnostics, and guarded configuration changes over MCP or plain HTTP, plus a watcher for router-originated alerts.
Inspect system, internet, interface, traffic, VPN, Wi-Fi, mesh, storage, OPKG, web-access, DHCP, firewall, port-forwarding, KeenDNS, DNS proxy, schedules, logs, and config state.
Scan nearby Wi-Fi/channel congestion and ping hosts from the router.
Manage clients: register/update, block/unblock, and set/remove static DHCP reservations.
Change router config with dry-run-by-default tools: port forwarding, KeenDNS mappings, static DNS records, and DHCP reservations.
Run protected raw read-only RCI queries for state without a dedicated tool.
Use diagnostics for logs by device, extender logs, watcher status/rule tests, config diffs, and backup status.
Trigger/back up config and MCP files to NAS, dump logs, list backups, and reboot the router.
Receive background watcher callouts when configured rules match.
Expose read-only tools over HTTP unless state-changing tools are explicitly allowlisted.
Provides tools for monitoring and managing Keenetic routers, including system status, internet connectivity, interfaces, traffic, VPN, WiFi, clients, DHCP, DNS, port forwarding, firewall rules, KeenDNS mappings, diagnostics, mesh nodes, storage, backups, and router configuration.
Keenetic MCP Server
MCP (Model Context Protocol) server for Keenetic routers. It runs directly on the router via Entware, with no dependencies outside the Python standard library. It gives an AI assistant 49 tools for monitoring and managing the router, reachable over MCP and over plain HTTP, plus a background watcher that calls out from the router when a rule matches.
Requirements
Item | Requirement |
Router | Keenetic with Entware support |
Storage | USB drive formatted as ext4, Entware installed on it |
Python | Python 3.x, standard library only ( |
Port | 9584 by default |
Architecture | Models | Status |
mipsel | KN-1010/1011, KN-1810, KN-1910, KN-2310, KN-3810 | Tested |
mips | KN-2410, KN-2510, KN-2010, KN-2110, KN-3610 | Should work, not tested |
Tested on Keenetic Giga KN-1010 + KN-1011 (Mesh), KeeneticOS 5.1.8 (5.01.C.8.0-2), Entware mipselsf.
Related MCP server: router-mcp
Installation
Step 1 — Install Entware
Format a USB drive as ext4 and plug it into the router. In the router web interface go to Applications -> OPKG and make sure the drive is selected as the storage.
Download the installer for the router model and copy it to the install folder on the USB drive via SMB (\\192.168.1.1):
KN-1010/1011, KN-1810, KN-1910, KN-2310, KN-3810: https://bin.entware.net/mipselsf-k3.4/installer/mipsel-installer.tar.gz
KN-2410, KN-2510, KN-2010, KN-2110, KN-3610: https://bin.entware.net/mipssf-k3.4/installer/mips-installer.tar.gz
Entware installs automatically. Check the router system log for:
[5/5] Installation of the "Entware" package system is complete!Step 2 — SSH into the router
ssh root@192.168.1.1 -p 222Default password: keenetic. Change it immediately:
passwdStep 3 — Run the installer
opkg update && opkg install curl && curl -fsSL -o /tmp/km-install.sh https://raw.githubusercontent.com/st412m/keenetic-mcp/main/install.sh && sh /tmp/km-install.shThe installer installs python3 if it is missing, puts the latest release into /opt/keenetic-mcp, writes .env with a random MCP_SECRET, sets up autostart and starts the server. The router's admin password is not needed: the server talks to the router's local RCI on 127.0.0.1:79.
It asks only what it cannot decide itself. Every question shows its default in brackets; Enter takes it.
Publish the server on the internet — asked when KeenDNS is set up on the router. Yes publishes it as
https://keenetic-mcp.<your KeenDNS name>, which is what claude.ai needs. Without KeenDNS the installer prints how to publish laterAdmin password for the extenders — asked when mesh extenders are found. The password lets
get_extender_logread their logs; Enter skips itPort — asked only if 9584 is already taken
Router address and admin password — asked only if the router does not answer on its local RCI
At the end it prints the LAN address and, if published, the internet address. Both carry the secret.
Options, a second copy next to the first, manual installation with git: docs/installation.md.
Step 4 — Connect to Claude
Updating
Run the command from Step 3 again. .env and watch_rules.json are kept, the autostart script is rewritten, and the previous version stays in /opt/keenetic-mcp.prev.
After adding or removing tools, or after a release that changes tool titles or annotations, start a new chat: MCP clients cache tools/list for the lifetime of a session.
Uninstall
sh /opt/keenetic-mcp/install.sh --uninstallConfiguration
Settings live in .env next to server.py, read once at startup. The installer writes the few lines a server needs; everything else keeps its default until added. .env.example lists every setting.
Variable | Default | Purpose |
|
| Router RCI. The default is the router's local RCI, which needs no password |
|
| Only if the router asks for a password, or to read mesh extender logs |
|
| Secret token in the URL path, and the listening port |
|
| KeenDNS name this server is published under; always protected from the write tools |
| empty | External ports the write tools must never forward or remove |
| empty | KeenDNS proxy names the write tools must never change |
| empty |
|
|
| Plain-HTTP tool route on or off |
| empty | State-changing tools allowed over that route |
|
| Event watcher, and its rules file |
|
| Scheduled router config backup, in cron format |
| empty | rsync-over-SSH destination; without it backups stay local |
|
| Also back up |
Full reference, including the protected-object rules: docs/configuration.md.
The watcher stays idle until it has rules. To turn it on, copy the example and edit it:
cp watch_rules.example.json watch_rules.json
vi watch_rules.jsonConnecting to claude.ai
The installer prints the internet address when it publishes the server via KeenDNS:
https://keenetic-mcp.YOUR_DDNS.keenetic.link/YOUR_MCP_SECRETIn claude.ai go to Settings → Connectors → Add custom connector and paste that URL. To see the addresses again:
sh /opt/keenetic-mcp/install.sh --show-urlWith your own reverse proxy instead of KeenDNS, point it at http://<router LAN address>:9584 and use its address with /YOUR_MCP_SECRET appended.
Tools
49 tools. One line per group; full descriptions in docs/tools.md.
System —
get_system_info,get_internet_status,get_interfaces,get_traffic,get_vpn_statusWiFi —
get_wifi,get_wifi_stations,get_site_survey,get_channel_analysisClients —
get_clients,get_unregistered_clients,get_dhcp_leases,get_dhcp_static,register_client,update_client,block_client,unblock_clientConfig, read-only —
get_config,get_config_state,diff_saved_config,get_port_forwarding,get_firewall_rules,get_keendns_mappings,get_dns_proxy,get_schedule,rci_queryConfig, write —
set_port_forwarding,remove_port_forwarding,set_keendns_mapping,remove_keendns_mapping,set_dhcp_host,remove_dhcp_host,set_dns_host,remove_dns_hostDiagnostics —
get_log,get_log_by_device,run_ping,get_watch_status,test_watch_ruleMesh —
get_mesh_nodes,get_extender_logStorage —
get_media,get_opkg_statusBackups and management —
backup_config,backup_mcp_config,list_backups,dump_log,rebootSecurity —
get_web_access
Every write tool takes dry_run, defaulting to true: it returns the payload it would send and changes nothing.
Beyond MCP, the tools are also reachable as GET /<MCP_SECRET>/tool/<name>?arg=value — see docs/http-api.md. The push side, where the router calls out on a matching event, is docs/watcher.md. Backups are docs/backup.md.
Limitations
The server is single-threaded: it handles one request at a time, so a polling loop blocks MCP calls. Keep poll intervals at 60 s or more
get_logreads only the lastlinesentries, which is fast; with a filter or a time window it searches the last 2000 entries, about 4 s, and says so when older entries were not read.get_site_surveyandget_channel_analysisare also slow. None of them belong in a polling loopA write tool polls for up to 7 s waiting for the save to land on disk, then answers
pendingrather than claiming successMCP clients cache
tools/listfor the lifetime of a session. A changed tool list, including changed titles or annotations, needs a new chatThe plain-HTTP route serves read-only tools only. State-changing tools return 403 unless allowlisted
The watcher keeps its state in
/tmp(RAM), so a router reboot resets its baselinemipsarchitecture is untested.mipselis tested on KeeneticOS 5.1.8; other firmware branches are notLog timestamps from before NTP syncs are wrong.
get_logflags them but asince/untilwindow still matches them
Troubleshooting
Symptom | Command |
Port 9584 does not answer |
|
|
|
Nothing in the log |
|
⚠️ If /opt is not mounted, never rebind the OPKG drive over SSH on the router itself: dropbear lives on /opt and the rebind kills the session before it completes. Use the web interface or another machine.
More symptoms: docs/troubleshooting.md.
Security
The endpoint is protected by a secret token in the URL path. HTTPS is handled by the Keenetic built-in SSL certificate
Never commit
.env— it is in.gitignore. Change the default SSH password after installationrci_queryis GET-only and cannot modify the router;crypto,ppp,userandrunning-configsubtrees are refused outrightget_configmasks secrets by default.include_secrets: trueputs passwords and keys into the chat transcriptThe write tools always protect the server's own port, upstream and proxy name. Add anything else via
MCP_PROTECTED_*. Protection applies to creating a rule as well as removing one, so listing a port also forbids re-publishing that service to the WANset_dns_hostis not covered byMCP_PROTECTED_*. What guards an existing record is that a name already resolving elsewhere is refusedThe plain-HTTP route serves read-only tools only. Adding a tool to
MCP_HTTP_TOOL_ALLOWLISThands out a write key: the URL secret ends up in config files, automation traces and proxy logs.MCP_HTTP_TOOLS=falseturns the route offTreat
watch_rules.jsonas credential material — it can carry bot tokens and internal URLs. Prefer$NAMEplaceholders resolved from.envbackup_mcp_configcopies.envandwatch_rules.jsonto the backup destination in clear text. Restrict that share to one accounttest_watch_rulemasks credentials in what it renders, not in what it sends:dry_run: falsesends the real values
Links
docs/ — installation, configuration, tools, HTTP API, watcher, backups, troubleshooting, internals
CHANGELOG.md — version history
LICENSE — MIT
Available Tools
49 toolsbackup_configBack up router configADestructive
Manually trigger a router config backup right now
Inputs: no named parameters.
backup_mcp_configBack up MCP config filesADestructiveIdempotent
Back up this server's own files that no release or git pull restores (.env, watch_rules.json, the Entware init script) to the NAS. Refreshes the mcp-config/ mirror every run and writes a dated snapshot only when the content changed. Runs synchronously and reports what happened, including a round-trip md5 check of the mirror. Staging is in /tmp (RAM): nothing is written to the USB stick.
Inputs: verify.
block_clientBlock clientADestructiveIdempotent
Block a device by MAC address. An unregistered device is registered as 'Blocked Device' first. Undo with unblock_client.
Inputs: mac (required).
diff_saved_configDiff unsaved configARead-onlyIdempotent
Diff running-config against startup-config, both read via RCI - a direct, checksum-independent answer to 'what is not saved yet'. Returns only_in_running and only_in_startup line lists; both empty means fully saved. Secrets are masked on both sides before comparing. Not wired into the write tools - call it on demand, not after every write.
Inputs: no named parameters.
dump_logDump router log to NASA
Snapshot the current router log and rsync it to the NAS backup path (RAM-only staging, no flash writes). Useful to preserve the log before a reboot.
Inputs: no named parameters.
get_channel_analysisAnalyze Wi-Fi channelsARead-onlyIdempotent
Analyze WiFi channel congestion and recommend the least busy channel
Inputs: no named parameters.
get_clientsList clientsARead-onlyIdempotent
Get list of connected clients (devices) in the network. Each client includes a 'node' field (controller/extender) indicating which mesh node it is connected to.
Inputs: no named parameters.
get_configRead running configARead-onlyIdempotent
Read the router's running-config with an optional regex filter. Secrets (md5/nthash/psk/password/private-key) are masked unless include_secrets is true. Examples: filter='ip static' for port forwarding, 'access-list' for firewall, 'ip dhcp host' for static reservations, 'ip http proxy' for KeenDNS.
Inputs: limit, filter, include_secrets.
get_config_stateGet config save stateARead-onlyIdempotent
Parsed show/last-change: when the config was last touched (date given both in MSK and UTC), which agent and user touched it, and the checksum - the only reliable signal that a save has actually landed on disk. The raw fail-safe block is included as-is, but its 'unsaved' field is NOT a save indicator - it can read false while a save is still in flight. Compare 'checksum' across two calls instead.
Inputs: no named parameters.
get_dhcp_leasesList DHCP leasesARead-onlyIdempotent
Devices holding a lease from the DHCP pool, with expiry time. Fixed reservations are not leases: see get_dhcp_static.
Inputs: no named parameters.
get_dhcp_staticList static DHCP reservationsARead-onlyIdempotent
List static DHCP reservations ('ip dhcp host'). Unlike get_dhcp_leases, which only shows dynamic pool leases, this shows fixed bindings.
Inputs: no named parameters.
get_dns_proxyGet DNS proxy statusARead-onlyIdempotent
DNS proxy status: upstream resolvers (with DoT SNI), the static A/AAAA records the proxy serves (parsed into domain/address), and the 'ip host' config tree that set_dns_host/remove_dns_host write to. A missing proxy-status block is reported as an error, not as an empty list.
Inputs: no named parameters.
get_extender_logRead extender logARead-onlyIdempotent
Get system log from mesh extender(s). Extenders are discovered automatically. If extender_ip is not specified, fetches logs from all active extenders.
Inputs: lines, filter, extender_ip.
get_firewall_rulesList firewall rulesARead-onlyIdempotent
List firewall rules: access-lists with their entries, ip firewall settings and interface access-groups
Inputs: no named parameters.
get_interfacesGet interfacesARead-onlyIdempotent
Get network interfaces status and traffic stats
Inputs: no named parameters.
get_internet_statusGet internet statusARead-onlyIdempotent
Internet connections that are up: address (the external IP), uptime, default-route flag, priority. Firmware, load and uptime of the router itself are in get_system_info.
Inputs: no named parameters.
get_keendns_mappingsList KeenDNS mappingsARead-onlyIdempotent
KeenDNS / web-access mappings from running-config ('ip http proxy'). Complements get_web_access, which reads the generated nginx config instead.
Inputs: no named parameters.
get_logRead router logARead-onlyIdempotent
Get system log entries with timestamps. Supports an optional time window via since/until ('HH:MM', 'HH:MM:SS' or 'Jul 24 08:00'). For lines about one device (by MAC, IP or name) use get_log_by_device.
Inputs: lines, since, until, filter.
get_log_by_deviceRead log by deviceARead-onlyIdempotent
Router log lines about one device: the given MAC, IP or name is expanded to all of that device's known MACs, IPs and names. No time window; for the whole log or since/until use get_log.
Inputs: device (required), lines.
get_mediaGet storage overviewARead-onlyIdempotent
Storage overview: internal flash and USB drives with partition UUID, label, filesystem, state, free space and which subsystem uses them (e.g. opkg). Use it to check whether the Entware drive is healthy.
Inputs: no named parameters.
get_mesh_nodesList mesh nodesARead-onlyIdempotent
Get Mesh Wi-Fi system nodes: controller and extenders with client count, firmware, uptime and connection speed
Inputs: no named parameters.
get_opkg_statusGet Entware statusARead-onlyIdempotent
Entware/OPKG state: which drive is bound, the initrc path, and whether /opt is actually mounted. If opt_mounted is false, keenetic-mcp itself is running on borrowed time.
Inputs: no named parameters.
get_port_forwardingList port forwardingARead-onlyIdempotent
List port forwarding / static NAT rules ('ip static') from running-config
Inputs: no named parameters.
get_scheduleList schedulesARead-onlyIdempotent
List router schedules (e.g. the firmware auto-update window) with name, weekday/time actions and seconds until the next fire. Answers with an explicit error, never an empty list, when the schedule trees cannot be read - 'no window is configured' and 'I could not read it' must not look alike to a caller deciding whether it may reboot the router.
Inputs: no named parameters.
get_site_surveyScan nearby Wi-Fi networksBRead-onlyIdempotent
Scan and list nearby WiFi networks
Inputs: no named parameters.
get_system_infoGet system infoARead-onlyIdempotent
Router firmware, model, uptime, CPU load and memory, plus this server's version and boot time. Internet connection and external IP are in get_internet_status.
Inputs: no named parameters.
get_trafficGet traffic summaryARead-onlyIdempotent
Get traffic summary for all active network interfaces (rx/tx bytes)
Inputs: no named parameters.
get_unregistered_clientsList unregistered clientsARead-onlyIdempotent
Get list of active but unregistered (unknown) devices in the network
Inputs: no named parameters.
get_vpn_statusGet VPN statusARead-onlyIdempotent
Get status of all VPN interfaces (WireGuard, IPsec, L2TP, PPTP)
Inputs: no named parameters.
get_watch_statusGet watcher statusARead-onlyIdempotent
Watcher status: whether the background event watcher is running, which rules file it read, the state of its own RCI session, and per rule - source, poll interval, cooldown, seconds to the next poll, match/sent/failed counters and the last delivery error. Use it to check that a rule is alive without waiting for the event it watches for.
Inputs: no named parameters.
get_web_accessList published web appsARead-onlyIdempotent
Web apps published via KeenDNS as the router serves them now (generated nginx config). Configured mappings with their upstreams are in get_keendns_mappings.
Inputs: no named parameters.
get_wifiGet Wi-Fi statusBRead-onlyIdempotent
Get WiFi radio status: channel, bandwidth, bitrate, temperature, connected stations count
Inputs: no named parameters.
get_wifi_stationsList Wi-Fi stationsARead-onlyIdempotent
Get currently associated WiFi stations with signal strength, traffic, device name and mesh node (controller/extender)
Inputs: no named parameters.
list_backupsList backups on NASARead-onlyIdempotent
List config backup files already present on the NAS (rsync --list-only). Confirms that scheduled backups actually arrived.
Inputs: no named parameters.
rci_queryQuery RCI treeARead-onlyIdempotent
Raw READ-ONLY query against the router's RCI tree. Performs GET /rci/show/ - it cannot write, because writing requires a POST body and this tool never sends one. Use it to explore state that has no dedicated tool yet. Useful paths: 'clock', 'schedule', 'dns-proxy', 'media', 'ntp', 'ip/hotspot', 'interface/GigabitEthernet1', 'components', 'ndns', 'update'. Blacklisted: running-config (use get_config), crypto, ppp, user.
Inputs: path (required), config_tree.
rebootReboot routerADestructive
Reboot the router. Takes effect at once and cannot be cancelled; this server is unreachable until the router has booted.
Inputs: no named parameters.
register_clientRegister clientCDestructiveIdempotent
Register a device by MAC address, assign a name and optionally a static IP
Inputs: mac (required), name (required), ip.
remove_dhcp_hostRemove static DHCP reservationADestructiveIdempotent
Delete a static DHCP reservation by MAC. dry_run is TRUE by default. Re-create with set_dhcp_host.
Inputs: mac (required), dry_run.
remove_dns_hostRemove static DNS recordADestructiveIdempotent
Delete a static DNS record ('no ip host '). The address is looked up in the config tree, because the router's removal form needs both the name and the address; pass it explicitly only to disambiguate a name that holds several. dry_run is TRUE by default. Re-create with set_dns_host.
Inputs: domain (required), address, dry_run.
remove_keendns_mappingRemove KeenDNS mappingADestructiveIdempotent
Delete a KeenDNS mapping by name. Protected names are refused. dry_run is TRUE by default. Re-create with set_keendns_mapping.
Inputs: name (required), dry_run.
remove_port_forwardingRemove port forwarding ruleADestructiveIdempotent
Delete a port forwarding rule, selected by index (from get_port_forwarding) or by port. Refuses ambiguous matches and protected ports. dry_run is TRUE by default. Re-create with set_port_forwarding.
Inputs: port, index, dry_run, protocol.
run_pingPing hostBRead-onlyIdempotent
Ping a host from the router and return latency and packet loss
Inputs: host (required), count.
set_dhcp_hostSet static DHCP reservationADestructiveIdempotent
Create or update a static DHCP reservation ('ip dhcp host'). Refuses an IP already reserved for a different MAC. The device NAME lives in the known-host tree - use register_client/update_client for that. dry_run is TRUE by default.
Inputs: ip (required), mac (required), dry_run.
set_dns_hostAdd static DNS recordAIdempotent
Create a static DNS record ('ip host ') served by the router's own DNS proxy - the LAN half of a split-horizon setup, where the same name must resolve to an internal reverse proxy inside the network and to the WAN address outside it. A name that already resolves to a different address is refused rather than extended: 'ip host' accepts several addresses per name and would round-robin it. Remove the old record first. dry_run is TRUE by default; a real write is saved to startup-config and verified by re-reading the tree.
Inputs: domain (required), address (required), dry_run.
set_keendns_mappingSet KeenDNS mappingADestructiveIdempotent
Create or update a KeenDNS web-access mapping ('ip http proxy'): name -> upstream host:port, published on the ndns domain with ssl redirect. Protected names (this server's own and MCP_PROTECTED_PROXY_NAMES) are refused in code. dry_run is TRUE by default.
Inputs: host (required), name (required), port (required), proto, +2 more.
set_port_forwardingSet port forwarding ruleADestructive
Create or update a port forwarding rule ('ip static'). The target is addressed by MAC: pass to_host as a MAC, or as an IP that belongs to a registered host (it is resolved, and refused if unknown). dry_run is TRUE by default - it returns the payload without sending it. A real write is saved to startup-config and verified by re-reading the tree. Protected ports (this server's own and MCP_PROTECTED_PORTS) are refused in code.
Inputs: port (required), to_host (required), enable, comment, +5 more.
test_watch_ruleTest watcher ruleADestructive
Render a watcher rule's outbound HTTP call with sample event values, so the URL, headers and body can be inspected before a real event fires. Credentials in the rendered view are masked; the call itself, when sent, uses the real values. dry_run is TRUE by default and sends nothing; dry_run=false performs the call for real, which is how to prove the receiver is reachable from the router.
Inputs: rule_id (required), dry_run.
unblock_clientUnblock clientADestructiveIdempotent
Unblock a device blocked by block_client, by MAC address.
Inputs: mac (required).
update_clientUpdate clientBDestructiveIdempotent
Update name or static IP of a registered device
Inputs: mac (required), ip, name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 49 tools
The descriptions actively pre-empt confusion, e.g. get_dhcp_static vs get_dhcp_leases, get_keendns_mappings vs get_web_access, and get_log vs get_log_by_device are explicitly contrasted. A few boundaries are softer (get_config vs rci_query vs get_config_state, get_traffic vs get_interfaces), but each tool still has a distinguishable target.
A clear verb_noun snake_case convention dominates (get_*, set_*, remove_*, backup_*, register_client, block_client). Minor outliers like dump_log, reboot, rci_query and diff_saved_config are still readable and domain-appropriate, so the pattern remains predictable.
49 tools is heavy for a single-router management server, and several read tools (get_config, rci_query, multiple log getters) stack on overlapping ground. Many operations earn their place individually, but the surface is large enough that an agent must scan a long list to pick.
Coverage is broad: full lifecycle for DHCP reservations, DNS hosts, port forwarding and KeenDNS mappings, plus logs, backups, mesh, WiFi, VPN status and a read-only escape hatch (rci_query). Gaps are mostly deliberate read-only areas (firewall rules, VPN configuration) rather than dead ends.
Maintenance
Related MCP Connectors
Syslog receiver and MCP server for homelab log intelligence.
Syslog receiver and MCP server for homelab log intelligence.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for querying connected WiFi devices from MikroTik RouterOS, enriched with DHCP leases and ARP table entries.MIT
- AlicenseAqualityDmaintenanceMCP server for monitoring and controlling WiFi routers (OpenWrt) via SSH, enabling device listing, status checks, WiFi configuration, rebooting, and more.717 npmMIT
- AlicenseAqualityBmaintenanceAn MCP server that lets an AI assistant manage your Keenetic router in plain language — list connected devices, pin static DHCP leases, rename devices, check WAN status, and reboot.10MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that bridges AI assistants like Claude Code to Keenetic routers, enabling natural language control of Wi-Fi, devices, VPN, and network segmentation via the router's RCI interface.MIT