Skip to main content
Glama

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 (requirements.txt lists no packages)

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):

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 222

Default password: keenetic. Change it immediately:

passwd

Step 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.sh

The 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 later

  • Admin password for the extenders — asked when mesh extenders are found. The password lets get_extender_log read their logs; Enter skips it

  • Port — 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

See Connecting to claude.ai.

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 --uninstall

Configuration

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

KEENETIC_HOST

http://127.0.0.1:79

Router RCI. The default is the router's local RCI, which needs no password

KEENETIC_USER / KEENETIC_PASS

admin, empty

Only if the router asks for a password, or to read mesh extender logs

MCP_SECRET / MCP_PORT

changeme, 9584

Secret token in the URL path, and the listening port

MCP_PROXY_NAME

keenetic-mcp

KeenDNS name this server is published under; always protected from the write tools

MCP_PROTECTED_PORTS

empty

External ports the write tools must never forward or remove

MCP_PROTECTED_PROXY_NAMES

empty

KeenDNS proxy names the write tools must never change

MCP_PROTECTED_UPSTREAMS

empty

host:port upstreams the write tools must never point at

MCP_HTTP_TOOLS

true

Plain-HTTP tool route on or off

MCP_HTTP_TOOL_ALLOWLIST

empty

State-changing tools allowed over that route

MCP_WATCH / MCP_WATCH_RULES

true, watch_rules.json

Event watcher, and its rules file

BACKUP_ENABLED / BACKUP_SCHEDULE

false, 0 11 * * 0

Scheduled router config backup, in cron format

BACKUP_RSYNC_HOST / _USER / _KEY / _PATH

empty

rsync-over-SSH destination; without it backups stay local

BACKUP_MCP_CONFIG

true

Also back up .env, watch_rules.json and the init script

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

Connecting 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_SECRET

In 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-url

With 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_status

  • WiFi — get_wifi, get_wifi_stations, get_site_survey, get_channel_analysis

  • Clients — get_clients, get_unregistered_clients, get_dhcp_leases, get_dhcp_static, register_client, update_client, block_client, unblock_client

  • Config, 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_query

  • Config, write — set_port_forwarding, remove_port_forwarding, set_keendns_mapping, remove_keendns_mapping, set_dhcp_host, remove_dhcp_host, set_dns_host, remove_dns_host

  • Diagnostics — get_log, get_log_by_device, run_ping, get_watch_status, test_watch_rule

  • Mesh — get_mesh_nodes, get_extender_log

  • Storage — get_media, get_opkg_status

  • Backups and management — backup_config, backup_mcp_config, list_backups, dump_log, reboot

  • Security — 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_log reads only the last lines entries, 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_survey and get_channel_analysis are also slow. None of them belong in a polling loop

  • A write tool polls for up to 7 s waiting for the save to land on disk, then answers pending rather than claiming success

  • MCP clients cache tools/list for the lifetime of a session. A changed tool list, including changed titles or annotations, needs a new chat

  • The 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 baseline

  • mips architecture is untested. mipsel is tested on KeeneticOS 5.1.8; other firmware branches are not

  • Log timestamps from before NTP syncs are wrong. get_log flags them but a since/until window still matches them

Troubleshooting

Symptom

Command

Port 9584 does not answer

/opt/etc/init.d/S99keenetic-mcp status then grep ' /opt ' /proc/mounts

Address already in use, old version answers

/opt/etc/init.d/S99keenetic-mcp status — it reports every live instance

Nothing in the log

cat /tmp/keenetic-mcp.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 installation

  • rci_query is GET-only and cannot modify the router; crypto, ppp, user and running-config subtrees are refused outright

  • get_config masks secrets by default. include_secrets: true puts passwords and keys into the chat transcript

  • The 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 WAN

  • set_dns_host is not covered by MCP_PROTECTED_*. What guards an existing record is that a name already resolving elsewhere is refused

  • The plain-HTTP route serves read-only tools only. Adding a tool to MCP_HTTP_TOOL_ALLOWLIST hands out a write key: the URL secret ends up in config files, automation traces and proxy logs. MCP_HTTP_TOOLS=false turns the route off

  • Treat watch_rules.json as credential material — it can carry bot tokens and internal URLs. Prefer $NAME placeholders resolved from .env

  • backup_mcp_config copies .env and watch_rules.json to the backup destination in clear text. Restrict that share to one account

  • test_watch_rule masks credentials in what it renders, not in what it sends: dry_run: false sends the real values

Available Tools

49 tools
backup_configBack up router configA
Destructive

Manually trigger a router config backup right now

Inputs: no named parameters.

backup_mcp_configBack up MCP config filesA
DestructiveIdempotent

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 clientA
DestructiveIdempotent

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 configA
Read-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 channelsA
Read-onlyIdempotent

Analyze WiFi channel congestion and recommend the least busy channel

Inputs: no named parameters.

get_clientsList clientsA
Read-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 configA
Read-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 stateA
Read-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 leasesA
Read-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 reservationsA
Read-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 statusA
Read-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 logA
Read-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 rulesA
Read-onlyIdempotent

List firewall rules: access-lists with their entries, ip firewall settings and interface access-groups

Inputs: no named parameters.

get_interfacesGet interfacesA
Read-onlyIdempotent

Get network interfaces status and traffic stats

Inputs: no named parameters.

get_internet_statusGet internet statusA
Read-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 mappingsA
Read-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 logA
Read-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 deviceA
Read-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 overviewA
Read-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 nodesA
Read-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 statusA
Read-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 forwardingA
Read-onlyIdempotent

List port forwarding / static NAT rules ('ip static') from running-config

Inputs: no named parameters.

get_scheduleList schedulesA
Read-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 networksB
Read-onlyIdempotent

Scan and list nearby WiFi networks

Inputs: no named parameters.

get_system_infoGet system infoA
Read-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 summaryA
Read-onlyIdempotent

Get traffic summary for all active network interfaces (rx/tx bytes)

Inputs: no named parameters.

get_unregistered_clientsList unregistered clientsA
Read-onlyIdempotent

Get list of active but unregistered (unknown) devices in the network

Inputs: no named parameters.

get_vpn_statusGet VPN statusA
Read-onlyIdempotent

Get status of all VPN interfaces (WireGuard, IPsec, L2TP, PPTP)

Inputs: no named parameters.

get_watch_statusGet watcher statusA
Read-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 appsA
Read-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 statusB
Read-onlyIdempotent

Get WiFi radio status: channel, bandwidth, bitrate, temperature, connected stations count

Inputs: no named parameters.

get_wifi_stationsList Wi-Fi stationsA
Read-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 NASA
Read-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 treeA
Read-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 routerA
Destructive

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 clientC
DestructiveIdempotent

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 reservationA
DestructiveIdempotent

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 recordA
DestructiveIdempotent

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 mappingA
DestructiveIdempotent

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 ruleA
DestructiveIdempotent

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 hostB
Read-onlyIdempotent

Ping a host from the router and return latency and packet loss

Inputs: host (required), count.

set_dhcp_hostSet static DHCP reservationA
DestructiveIdempotent

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 recordA
Idempotent

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 mappingA
DestructiveIdempotent

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 ruleA
Destructive

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 ruleA
Destructive

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 clientA
DestructiveIdempotent

Unblock a device blocked by block_client, by MAC address.

Inputs: mac (required).

update_clientUpdate clientB
DestructiveIdempotent

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

    A3.6/5.0

    Scored across 49 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers