keenetic-mcp
The keenetic-mcp server lets an MCP agent locally inspect and manage a Keenetic router through its RCI HTTP API, with unsaved changes discarded on reboot unless explicitly saved.
Read router system info, firmware/components, config state, devices, interfaces, routes, policies, Wi-Fi status, internet status, and network segments.
Diagnose connectivity with ping and traceroute.
Change device settings: rename, block/allow internet, assign routing policies, schedules, or priority.
Bring interfaces up or down.
Create and delete isolated network segments, optionally with Wi-Fi and routing policies.
Download configuration backups and explicitly save running configuration to startup.
Make raw RCI GET/POST calls for anything not covered by built-in tools.
Operate safely: read-only mode removes write tools, backups are taken before first change, and changes are verified by reading back.
Allows AI agents to control and monitor Keenetic routers, including querying device status, traffic, interfaces, Wi-Fi, routes, policies, and making configuration changes with safety features.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@keenetic-mcp who is using the most bandwidth right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.

keenetic-mcp
Control your Keenetic router from Claude, Codex, Cursor, or any MCP agent.
Ask your agent about your network in plain language. No USB stick, no Entware, nothing installed on the router.
> who is using the most bandwidth right now?
Three devices are active. Sorted by traffic:
work-laptop wifi:HomeNet -46 dBm 7.7 GB down
living-room-tv wired:Home 3.2 GB down
hallway-camera wifi:HomeNet -48 dBm 5.4 MB down
The laptop is on the 2.4 GHz radio at -46 dBm, which is a strong
signal, so the throughput is not a coverage problem.
> block the camera until tomorrow morning
Blocked hallway-camera (02:00:00:00:00:14).
Applied to the running configuration and verified, but NOT saved.
A reboot discards it. Backup taken before the change:
~/Library/Application Support/keenetic-mcp/backups/…txt
Say the word and I will make it permanent, or leave it and it
reverts on the next restart.Why
Nothing on the router. It talks to the router's own HTTP API over your LAN. No USB drive, no Entware, no firmware modification.
Works on any Keenetic. The tool set adapts to what your specific model and firmware actually support.
Safe by construction. Changes are never saved unless you ask, a backup is taken before the first one, and every change is read back and verified before it is reported as done.
Read-only if you want it. One flag and the agent physically cannot change anything.
Related MCP server: keenetic-mcp
Install
Claude Code
/plugin marketplace add salatmaster/keenetic-mcp
/plugin install keenetic@keeneticThen run the setup wizard in your terminal:
npx -y keenetic-mcp initCodex
codex plugin marketplace add salatmaster/keenetic-mcp
codex plugin add keenetic@keenetic
npx -y keenetic-mcp initThis brings the skills along with the server. For the server on its own:
codex mcp add keenetic -- npx -y keenetic-mcpAnything else
{
"mcpServers": {
"keenetic": { "command": "npx", "args": ["-y", "keenetic-mcp"] }
}
}The wizard finds your router from the default gateway, confirms it really is a Keenetic, checks the password against it, and stores the password in your operating system keychain. Only the address and login go in a settings file.
Prefer environment variables? KEENETIC_HOST, KEENETIC_USER and
KEENETIC_PASSWORD override everything, which is what you want in a container.
What it can do
Read
Tool | |
| every device, filtered by active, wired, wireless or blocked, sorted by traffic or signal |
| one device in full: lease, Wi-Fi rate, policy, schedule, traffic |
| WAN links, bridges, access points, VPN tunnels |
| one interface in full, including WireGuard peers |
| radios by band, with client counts |
| reachability, and which check failed |
| send ICMP echo requests, with an optional source interface |
| trace the network path using ICMP probes, with optional source interface, source address, and maximum hop count |
| routing table, or just the default route |
| connection policies for selective routing |
| model, firmware, CPU, memory, installed components |
| unsaved changes, who changed what and when |
| every bridge, and whether the web interface lists it as a segment |
| download the configuration into the tool's backups directory |
Change
Tool | |
| rename, block or allow, assign a routing policy, schedule or priority |
| bring an interface up or down |
| a guest or IoT network the web interface actually lists, with Wi-Fi, DHCP and optional VPN routing |
| remove a segment and everything created with it |
| make pending changes survive a reboot |
Escape hatch
Tool | |
| any router API path at all, for whatever the tools above do not cover |
Skills included
The plugin ships four skills, so the agent knows how your router behaves rather than guessing. One plugin directory serves both Claude Code and Codex: they read different manifests but share the same skills and the same server definition.
keenetic-rci teaches the router's API tree: which paths exist, which ones return 100 KB, and how to recover the exact syntax of a command from the router's own configuration.
keenetic-safe-changes teaches the change workflow: what the router's fail-safe does and does not protect against, and which interfaces will cut off your own access.
keenetic-segments covers building an isolated network the router will admit exists. The obvious way produces a guest network that carries traffic perfectly and never appears in the web interface, because a segment is VLAN-backed and the VLAN is the part everyone leaves out.
keenetic-troubleshoot is an ordered diagnostic playbook for "the internet is down", "Wi-Fi is bad" and "one device cannot connect".
Safety
Nothing is saved unless you ask. Changes apply to the running configuration and are discarded on reboot until
save_configis called. The server never calls it on its own.A backup is taken automatically before the first change of a session.
Every change is verified. The router accepts some wrong commands silently and changes nothing, so each write is read back and compared before it is reported as successful.
Read-only mode really is read-only. With
--read-only, the write tools are not registered at all rather than registered and refusing, so the agent never sees them.Your password goes in the system keychain, not in a config file, and never in a log or a tool response.
LAN only. No cloud, no telemetry, no outbound connection to anything but your router.
Where the password is stored on each platform, and how to report something privately, are in SECURITY.md.
Supported routers
RCI, the API this uses, is a standard part of KeeneticOS rather than a feature of expensive models, so this works across the range. Verified against a Keenetic Ultra (KN-1811) on KeeneticOS 5.1.3.
Models on the current 5.1 branch: Giga (KN-1010), Hero (KN-1011, KN-1012), Start and Starter (KN-1111, KN-1112, KN-1121), Air and Explorer (KN-1613, KN-1621), Extra and Carrier (KN-1713, KN-1714, KN-1721), Ultra and Titan (KN-1810, KN-1811, KN-1812). Older hardware on 4.x and earlier has RCI too; the tool set adapts to the components each router actually has.
Netcraze routers run the same firmware under their own brand and answer the same RCI. Verified read-only against a Netcraze Speedster (NC-3013) on 5.2 Beta 1: the setup wizard, system info, internet status and the device list.
Firmware 5.2 changed the login: newer 5.2 builds accept only ndw4, which needs Node 24.7 or later. On older Node the server falls back to the old login, which 5.1 still accepts and 5.2 may not. Verified on a Keenetic Hopper (KN-3810) on 5.2 Beta 4.
How it works
Keenetic routers expose RCI, a JSON mirror of their command-line tree, over HTTP. This server authenticates with the router's challenge-response scheme, keeps one session alive across the agent's questions, and shapes the answers so they fit in a model's context: the raw interface listing alone is 32 KB, and the NAT table is over 100 KB.
There is no coherent public documentation for RCI, so docs/rci-api.md is the notes taken while building this: the authentication handshake, the paths that exist, the traps, and how to recover a command's syntax from the router itself.
Development
npm install
npm test # no router required
npm run typecheck
npm run buildA checkout reports its version as 0.0.0-dev, because there is no version
written down anywhere in the sources. Put KEENETIC_MCP_VERSION in a .env at
the repository root to say otherwise; the same file can hold KEENETIC_HOST
and KEENETIC_PASSWORD so you do not have to export them. A real environment
variable always wins over that file, and an installed copy never reads one.
Tests run against sanitized fixtures captured from a real router. To refresh them, and to run a read-only smoke test against your own:
KEENETIC_HOST=… KEENETIC_PASSWORD=… npm run capture:fixtures
KEENETIC_TEST_HOST=… KEENETIC_TEST_PASSWORD=… npm run smokeFixtures are anonymized deterministically and a test scans the whole repository for anything that looks like a real MAC address, private IP or key.
The setup wizard reads a password from the terminal, which no unit test can reach: piped input takes a different code path entirely. That part is checked with a script that drives a real pty, so it needs a terminal and cannot run in CI:
KEENETIC_TEST_PASSWORD=… ./scripts/verify-wizard.expReleasing
A release is a tag and nothing else. There is no version commit to write,
because there is no version in the repository to change: package.json carries
0.0.0-dev, the plugin manifests carry none at all, and the release workflow
stamps the tag into package.json immediately before publishing without
committing it.
git tag v0.2.2 && git push origin v0.2.2The workflow refuses a tag that does not name a version, and a test refuses a
tree that has a version written into it, so the two can never disagree. The
plugins pin keenetic-mcp@^0, which tracks the major only and is meant to be
edited once, at 1.0.
License
MIT
Available Tools
20 toolsbackup_configDownload a configuration backupARead-only
Saves the router startup configuration into this tool's backups directory (KEENETIC_STATE_DIR/backups) with owner-only file permissions. Take one before any sequence of changes so there is a known-good state to return to. Reading the configuration changes nothing on the router.
Inputs: no named parameters.
create_segmentCreate a network segmentADestructive
Creates an isolated network that the web interface actually lists as a segment: a VLAN subinterface trunked over every switch port, a bridge, an address, NAT, a DHCP pool, and optionally a Wi-Fi network and a routing policy. Free identifiers are chosen automatically. The result is verified against the router-computed iseg block, and a failure anywhere rolls the whole thing back. Nothing is saved; call save_config once the user confirms.
Inputs: name (required), psk, ssid, subnet, +2 more.
delete_segmentDelete a network segmentADestructive
Removes a segment and everything created with it: the Wi-Fi networks bound to it, its policy, its DHCP pool, NAT, the bridge, and the VLAN on every switch port. Removing the bridge alone leaves the VLAN trunked over the whole switch. Devices on the segment lose their connection. Refuses the home segment.
Inputs: bridge (required).
get_config_stateConfiguration stateARead-only
Whether the running configuration has unsaved changes, who last changed it and when, and the state of the router fail-safe timer. Unsaved changes are lost on reboot. unsavedChanges is null when the saved checksum could not be read - treat that as unknown, not as saved.
Inputs: no named parameters.
get_deviceGet one device in fullARead-only
Every field the router holds for a single device: DHCP lease, Wi-Fi rate and mode, access policy, traffic shaping, first and last seen. Identify it by MAC, IP or name.
Inputs: ip, mac, name.
get_interfaceGet one interface in fullARead-only
Every field for a single interface, including protocol-specific detail such as WireGuard peers or PPPoE session state. Get the exact name from list_interfaces first.
Inputs: name (required).
get_internet_statusInternet connectivityARead-only
Whether the router currently reaches the internet, and which check failed if not: gateway reachability, DNS resolution, and captive-portal detection. Start here when the user reports the internet is down.
Inputs: no named parameters.
get_system_infoRouter system informationARead-only
Model, firmware version, uptime, CPU and memory load, and the list of installed KeeneticOS components. Call this first when you need to know what the router supports: the component list tells you which features exist on this device. Judge memory pressure by memoryAvailableKb, not memoryFreeKb: free excludes the page cache the kernel releases on demand, so it is always low on a healthy router.
Inputs: no named parameters.
get_wifi_statusWi-Fi statusARead-only
Wi-Fi radios grouped by band, each with its access points, SSIDs, link state and the number of connected clients. Use this rather than list_interfaces when the question is about Wi-Fi coverage or which network a device should be on.
Inputs: no named parameters.
list_devicesList devices on the networkARead-only
Every device the router knows about, with IP, name, how it is connected, signal strength and traffic counters. Use filter to narrow to active, wired, wireless or blocked devices, and sort to rank by traffic, name, signal or last seen.
Inputs: sort, limit, filter.
list_interfacesList network interfacesBRead-only
Every interface on the router - WAN links, bridges, Wi-Fi access points and VPN tunnels - with link state, address and whether it carries the default route. Summary detail is the default because the full listing is very large.
Inputs: kind, limit, detail.
list_policiesList routing policiesARead-only
Connection policies, which decide that a given device leaves through a given link - typically used to send some devices through a VPN tunnel and the rest direct. The names returned here are what a device is assigned to.
Inputs: no named parameters.
list_routesList IP routesARead-only
The routing table: destination, gateway, outgoing interface and metric. Use kind=default to see only the default route, which tells you which link traffic leaves through.
Inputs: kind, limit.
list_segmentsList network segmentsARead-only
Every bridge on the router, and whether the web interface lists it as a segment. A bridge that carries an address but has no VLAN behind it works for traffic and never appears under /access-points, so uiVisible is the field that matters.
Inputs: no named parameters.
pingPingBRead-only
Send ICMP echo requests to a hostname or IPv4 address through the router. Supports a configurable packet count and source interface, and returns the collected ping output.
Inputs: host (required), count, source_interface.
rci_callCall the router API directlyADestructive
Sends a raw request to the router RCI interface, for anything the other tools do not cover. GET reads a path such as "show/version" or "interface/Bridge0"; POST sends a command object mirroring the CLI tree. The response is capped, so ask for a narrow path rather than a broad one: show/ip/nat alone is over 100 KB.
Inputs: method (required), body, path, max_bytes.
save_configSave the configurationADestructiveIdempotent
Writes the running configuration to the startup configuration, so pending changes survive a reboot. Nothing else in this server saves, so call this only once the user has confirmed the changes are what they want.
Inputs: no named parameters.
set_interface_stateBring an interface up or downADestructiveIdempotent
Enables or disables a network interface. Taking down a bridge or the WAN link can cut off access to the router itself, including this connection. Confirm what the interface carries with get_interface before calling this.
Inputs: name (required), state (required).
tracerouteTracerouteARead-only
Trace the network path to a hostname or IPv4 address using ICMP probes. Supports selecting the source interface, source IPv4 address, and maximum number of hops (default: 30). Returns the collected hop-by-hop traceroute output.
Inputs: host (required), max_hops, source_address, source_interface.
update_deviceChange a deviceADestructiveIdempotent
Rename a device, allow or block its internet access, put it on a routing policy or a schedule, or set its traffic priority. Changes apply immediately but are NOT saved: a reboot discards them until save_config is called.
Inputs: mac (required), name, access, policy, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a distinct resource+action target (routes vs policies vs segments vs interfaces vs devices), and the descriptions explicitly resolve the few naturally overlapping cases — e.g. 'use get_wifi_status rather than list_interfaces', 'uiVisible is the field that matters' for list_segments, and rci_call is documented as the deliberate fallback for everything else. The list_/get_ pairings (list_devices/get_device, list_interfaces/get_interface) are unambiguous summary-vs-detail splits rather than duplicates.
The dominant convention is verb_noun snake_case (get_system_info, list_segments, create_segment, delete_segment, update_device, save_config, backup_config) and it is applied consistently. Minor deviations exist: set_interface_state uses 'set_' where update_device uses 'update_', and ping/traceroute/rci_call are bare verbs or single tokens, though these read naturally as conventional command names.
20 tools is on the heavy side of the 3-15 sweet spot, but for a router administration surface spanning system, routing, Wi-Fi, segments, devices, interfaces, diagnostics and config persistence, each tool maps to a real capability and none looks like filler. Slightly over-scoped rather than bloated.
Strong lifecycle coverage for segments (create/list/delete with rollback and verification) plus a coherent config-safety story (backup_config, save_config, get_config_state) and network diagnostics. Gaps remain: no direct Wi-Fi/SSID credential editing, no interface or tunnel creation, no policy creation, and no reboot/firmware tool — all reachable only via raw rci_call, which is a workable but less safe escape hatch.
Maintenance
Related MCP Connectors
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
MCP server enabling AI agents to manage Bitrix24 features via standardized protocol
Open-source MCP gateway with per-agent tool permissions, call approvals and tool-change review.
Related MCP Servers
- 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
- AlicenseBqualityCmaintenanceEnables AI agents to manage Keenetic routers through the same RCI API used by the router's web interface, working directly over the local network without cloud involvement. It supports reading device statuses and executing configuration changes, with confirm, dry-run, and destructive-action safeguards.23PolyForm Noncommercial 1.0.0
- AlicenseAqualityBmaintenanceEnables AI clients to perform controlled diagnostics and configuration of Keenetic and Netcraze routers over LAN RCI or remote KeenDNS HTTPS, with read-only mode, guarded writes, and centralized secret masking.19MIT