keenetic-mcp

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 yourLAN. No USB drive, no Entware, no firmware modification.
• Works on any Keenetic. The tool set adapts to what your specific model andfirmware actually support.
• Safe by construction. Changes are never saved unless you ask, a backup istaken before the first one, and every change is read back and verified beforeit is reported as done.
• Read-only if you want it. One flag and the agent physically cannot changeanything.

Install

Claude Code

/plugin marketplace add salatmaster/keenetic-mcp
/plugin install keenetic@keenetic

Then run the setup wizard in your terminal:

npx -y keenetic-mcp init

Codex

codex plugin marketplace add salatmaster/keenetic-mcp
codex plugin add keenetic@keenetic
npx -y keenetic-mcp init

This brings the skills along with the server. For the server on its own:

codex mcp add keenetic -- npx -y keenetic-mcp

Anything else

{
  "mcpServers": {
    "keenetic": { "command": "npx", "args": ["-y", "keenetic-mcp"] }
  }
}

The wizard finds your router from the default gateway, confirms it really is aKeenetic, checks the password against it, and stores the password in youroperating system keychain. Only the address and login go in a settings file.

Prefer environment variables? KEENETIC_HOST, KEENETIC_USER andKEENETIC_PASSWORD override everything, which is what you want in a container.

What it can do

Read

Change

Escape hatch

Skills included

The plugin ships three skills, so the agent knows how your router behaves ratherthan guessing. One plugin directory serves both Claude Code and Codex: they readdifferent manifests but share the same skills and the same server definition.

• keenetic-rci teaches the router's API tree: which paths exist, which onesreturn 100 KB, and how to recover the exact syntax of a command from therouter's own configuration.
• keenetic-safe-changes teaches the change workflow: what the router'sfail-safe does and does not protect against, and which interfaces will cut offyour own access.
• keenetic-troubleshoot is an ordered diagnostic playbook for "the internetis down", "Wi-Fi is bad" and "one device cannot connect".

Safety

• Nothing is saved unless you ask. Changes apply to the runningconfiguration and are discarded on reboot until save_config is called. Theserver 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 silentlyand changes nothing, so each write is read back and compared before it isreported as successful.
• Read-only mode really is read-only. With --read-only, the write toolsare not registered at all rather than registered and refusing, so the agentnever sees them.
• Your password goes in the system keychain, not in a config file, and neverin a log or a tool response.
• LAN only. No cloud, no telemetry, no outbound connection to anything butyour router.

Supported routers

RCI, the API this uses, is a standard part of KeeneticOS rather than a featureof expensive models, so this works across the range. Verified against aKeenetic 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; thetool set adapts to the components each router actually has.

How it works

Keenetic routers expose RCI, a JSON mirror of their command-line tree, overHTTP. This server authenticates with the router's challenge-response scheme,keeps one session alive across the agent's questions, and shapes the answers sothey fit in a model's context: the raw interface listing alone is 32 KB, and theNAT table is over 100 KB.

There is no coherent public documentation for RCI, sodocs/rci-api.md is the notes taken while building this: theauthentication handshake, the paths that exist, the traps, and how to recover acommand's syntax from the router itself.

Development

npm install
npm test          # 190 tests, no router required
npm run typecheck
npm run build

Tests run against sanitized fixtures captured from a real router. To refreshthem, 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 smoke

Fixtures are anonymized deterministically and a test scans the whole repositoryfor 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 canreach: piped input takes a different code path entirely. That part is checkedwith a script that drives a real pty, so it needs a terminal and cannot run inCI:

KEENETIC_TEST_PASSWORD=… ./scripts/verify-wizard.exp

License

MIT