keenetic-mcp

An MCP server that lets an AI assistant (Claude, or any MCP client) manage your Keenetic router in plain language — list connected devices, pin static DHCP leases, rename devices, check WAN status, and reboot.

It talks to the router's built-in RCI JSON API over HTTP, so there's no cloud, no third-party service, and nothing leaves your network. You run it yourself against your own router.

Tested against a Keenetic Hopper DSL (KN-3610). The RCI API is shared across the Keenetic line (Giga, Viva, Hopper, Ultra, …), so other models should work too. If you confirm one, please open an issue/PR to grow the list.

Why

Keenetic's RCI API is powerful but poorly documented, and its auth is a fiddly two-step MD5-challenge + SHA256 dance that trips people up for hours. This wraps the common device/lease/WAN operations behind clean MCP tools so you can just say "pin the Raspberry Pi to a static IP" and it happens.

Related MCP server: vyos-mcp

Tools

Safety: write tools are off by default

Read tools always work. Write tools are disabled until you set KEENETIC_ENABLE_WRITES=1 in the server environment. This means a fresh install can look but not touch — no accidental reboots or lease changes while you explore. Even once enabled, write tools are guarded:

• pin_device refuses if the target IP is already active on, or statically reserved to, a different device.

• Address-like identifiers ("66") never fuzzy-match a device name (e.g. Room-66-Cam).

• Every write reads the RCI response back and reports status:error instead of silently "succeeding".

• reboot requires an explicit confirm=True.

Install

Requires Python 3.9+.

The easy way — no clone, no venv. With uv installed, run it straight from GitHub; your MCP client launches it on demand (see Connecting an MCP client). To install it as a command instead:

uv tool install "git+https://github.com/karyaboyraz/keenetic-mcp"
# or: pipx install "git+https://github.com/karyaboyraz/keenetic-mcp"

Then set your router password in the environment (KEENETIC_PASS) and run keenetic-router-mcp. By default it speaks stdio — the transport desktop MCP clients expect.

The installed command is keenetic-router-mcp. The GitHub repo is keenetic-mcp.

From source (for development or the systemd service):

git clone https://github.com/karyaboyraz/keenetic-mcp.git
cd keenetic-mcp
python3 -m venv .venv
.venv/bin/pip install .

cp .env.example .env
# edit .env: set KEENETIC_PASS (and KEENETIC_ENABLE_WRITES=1 if you want write tools)
.venv/bin/keenetic-router-mcp

Configuration

All configuration is via environment variables (see .env.example):

Connecting an MCP client

stdio — the client launches the server (recommended)

Most clients (Claude Desktop, Claude Code, Cursor, …) start the server themselves and talk over stdio. With uv installed, no prior install step is needed — uvx fetches from GitHub and runs it. Add to your client's MCP config (claude_desktop_config.json, ~/.mcp.json, etc.):

{
  "mcpServers": {
    "keenetic": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/karyaboyraz/keenetic-mcp", "keenetic-router-mcp"],
      "env": {
        "KEENETIC_URL": "http://192.168.1.1",
        "KEENETIC_PASS": "your-router-admin-password",
        "KEENETIC_ENABLE_WRITES": "0"
      }
    }
  }
}

If you installed it as a command (uv tool install / pipx), use "command": "keenetic-router-mcp" with no args. Restart the client (MCP config isn't hot-reloaded), then ask: "list my router's devices".

http — connect to a running network service

If you run it as a long-lived service (KEENETIC_TRANSPORT=http, see Running as a service), point the client at the URL instead:

{
  "mcpServers": {
    "keenetic": {
      "type": "http",
      "url": "http://127.0.0.1:8905/mcp"
    }
  }
}

Running as a service (Linux)

A keenetic-mcp.service systemd unit is included — it runs the server over HTTP (KEENETIC_TRANSPORT=http) so clients connect to it by URL. Put the repo at /opt/keenetic-mcp, create the venv there (python3 -m venv .venv && .venv/bin/pip install .), fill in .env, then:

sudo cp keenetic-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now keenetic-mcp

How the auth works

For anyone reusing the RCI API directly, this is the part that's hard to find. Keenetic uses a two-step challenge:

1. GET /auth → returns 401 with X-NDM-Realm and X-NDM-Challenge headers.

2. Compute md5 = MD5("<user>:<realm>:<pass>"), then sha = SHA256(challenge + md5).

3. POST /auth with {"login": user, "password": sha} → sets a session cookie.

4. POST /rci/ with a list[dict] command tree, using that cookie.

Write commands must be followed by [{"system":{"configuration":{"save":{}}}}] or they're lost on reboot. See server.py for the full, working implementation.

Security notes

• The server has full admin control of your router. Bind it to 127.0.0.1 (or a trusted LAN only) — never expose port 8905 to the internet.

• Your password lives only in .env (gitignored). Nothing is sent anywhere except your own router.

• This is not affiliated with or endorsed by Keenetic. Use at your own risk.

License

MIT — see LICENSE.