podkop-mcp

MCP server for managing Podkop and Forkop on OpenWrt over SSH.

Stop editing UCI by hand, remembering the uci add_list trap and passing base64-wrapped scripts to PowerShell. Ask your MCP client to add domains, list sections, inspect live connections, reload the service and roll back a bad change — with dry-run, backups and redaction built in.

Status: alpha. Live read-only tested against Forkop 1.0.5 and Forkop 2.0.0 (OpenWrt 25.12.6). Write/apply paths were verified in disposable OpenWrt Docker containers with real Forkop 2.0.0 and Podkop 0.7.24. Backend schema is revalidated every PODKOP_MCP_PROFILE_TTL seconds (default 30).

Why

Managing Podkop/Forkop by hand is error-prone:

• Forkop 1.x stores domains in one space-separated string (section.domain). One uci add_list turns it into an exact-match domain list and subdomains silently stop being routed.
• Forkop 2.x uses a multi-line section.destinations text with # comments.
• Podkop uses a real UCI list (section.user_domains).
• Forkop reloads asynchronously; a failed reload must be detected and rolled back.
• Subscription URLs and proxy strings are secrets and end up in logs.

Unlike MCP servers that run on the router itself, podkop-mcp runs on the administrator's machine, talks to OpenWrt over SSH and understands Podkop/Forkop semantics: dry-run, backups, rollback and secret redaction. All of that is hidden behind typed MCP tools.

Features

• SSH transport with a key from MCP parameters: key file, inline base64/PEM, or ~/.ssh/config alias. Host key verification, keepalive, timeouts.
• Backend detection: Forkop 1.x, Forkop 2.x, Podkop; capabilities derived from the installed CLI.
• Full UCI access via ubus call uci get JSON and uci for writes. Any option can be read or changed; the package is restricted to forkop/podkop.
• Domain operations that preserve the backend format: add/remove/replace, search coverage, suggest uncovered hosts from live connections, check FakeIP.
• Sections: list, inspect, create, update, enable/disable, delete with cascade of child subscriptions/URLTest items.
• Subscriptions and proxy groups: list, add, delete, update, test latency, select a proxy (Forkop 2.x).
• Monitoring: service/system status, health checks, logs, live connections, traffic rates, proxy delays.
• Safety: mutating tools are dry-run by default; apply=true creates a router-side backup, commits UCI, reloads and verifies. On failure the backup is restored automatically. PODKOP_MCP_READ_ONLY=1 blocks all writes.
• Secrets redacted by default: subscription URLs, proxy_string, keys, tokens. Raw export requires reveal_secrets=true.
• Bilingual docs (English / Russian) and CI.

Support matrix

Install

Requirements:

• Python 3.10+ (CI tests 3.10 through 3.14)
• OpenWrt router with Forkop or Podkop installed
• SSH key access to the router

Install from PyPI:

pip install podkop-mcp
# or run without installing
uvx podkop-mcp

Install from source:

git clone https://github.com/mikel38487/podkop-mcp.git
cd podkop-mcp
python -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .

Configure your MCP client (Claude Desktop, Cursor, DSH, etc.):

{
  "mcpServers": {
    "podkop": {
      "command": "podkop-mcp",
      "env": {
        "PODKOP_MCP_SSH_HOST": "192.168.1.1",
        "PODKOP_MCP_SSH_USER": "root",
        "PODKOP_MCP_SSH_KEY_PATH": "C:/Users/<user>/.ssh/router_key",
        "PODKOP_MCP_KNOWN_HOSTS": "C:/Users/<user>/.ssh/known_hosts",
        "PODKOP_MCP_HOST_KEY_POLICY": "reject"
      }
    }
  }
}

Or use an existing ~/.ssh/config alias:

"env": {
  "PODKOP_MCP_SSH_CONFIG_HOST": "router-home",
  "PODKOP_MCP_SSH_KEY_PATH": "C:/Users/<user>/.ssh/router_key",
  "PODKOP_MCP_HOST_KEY_POLICY": "reject"
}

Host key policy defaults to reject. Add the router key to known_hosts first (for example with a normal ssh login). accept-new is a one-time TOFU convenience for a new router; it does not protect against a MITM on the first connection.

Ask the model:

• “Run podkop_doctor and show the backend version.”
• “Add example.com and cdn.example.com to main; show me the diff first.”
• “List sections with domain counts.”
• “Which hosts in live connections are not covered by any section?”
• “Show traffic for the last 2 seconds and the top clients.”
• “Disable the youtube section and reload.”

Documentation

• Tool reference · Справочник инструментов
• Architecture · Архитектура
• Compatibility · Совместимость
• Troubleshooting · Диагностика
• Testing in OpenWrt Docker · Тестирование в Docker
• Security · Безопасность
• Security policy, contributing

How write operations work

dry-run (default)
  → read config, compute normalized diff, show uci commands

apply=true
  → cp /etc/config/<pkg> /etc/podkop-mcp/backups/<ts>-<reason>.uci
  → uci set/add_list/delete (package restricted to forkop/podkop)
  → uci commit
  → /etc/init.d/<pkg> reload
  → poll get_status up to ~35 s
  → on failure: restore backup, commit, reload
  → return diff, backup id, health summary

No command is executed through a shell string built from user input; values are shell-quoted with shlex and the script is sent to sh via stdin. Paths are validated; no base64 applet is required on the router.

Tool overview

Full reference: docs/tools.md.

Configuration reference

To manage several routers, put them in a JSON file and point PODKOP_MCP_CONFIG at it:

{
  "targets": {
    "home": {"host": "192.0.2.10"},
    "office": {"host": "192.0.2.11", "port": 2222}
  },
  "default_target": "home"
}

"env": {
  "PODKOP_MCP_CONFIG": "~/.config/podkop-mcp/targets.json"
}

The default_target router (or the first one when it is omitted) is used when a tool call does not pass target; pass "target": "office" to use the other router. PODKOP_MCP_TARGET_NAME does not select a target from this file — it only names the single router defined by PODKOP_MCP_SSH_HOST / PODKOP_MCP_SSH_CONFIG_HOST.

Testing

python -m pytest -q                 # unit + fake router + live/docker skipped
python scripts/smoke_mcp.py         # MCP stdio handshake
PODKOP_MCP_LIVE=1 python -m pytest -q -m live   # read-only, real router

For the real SSH/UCI/apply path there is an OpenWrt Docker container: real openwrt/rootfs userland, real ubus/rpcd/dropbear/uci, with stubs for the Forkop CLI/init (no sing-box/nft).

.\scripts\openwrt-docker.ps1
. .\.tmp\openwrt-env.ps1
.\.venv\Scripts\python.exe -m pytest -q -m docker_ssh
.\scripts\openwrt-docker.ps1 -Stop

This is a container, not a VM: it shares the host kernel. Full VM instructions and limitations are in docs/testing.md. Live tests never write to the production router; write operations are tested in the Docker container and through the fake transport.

Limitations

• MCP transport is stdio; SSE/HTTP is out of scope.
• Reordering sections is not exposed yet (UCI order is file order); use export/edit
  • podkop_config_export if needed.
• Podkop subscription handling is best-effort; the active target is Forkop.
• Forkop 1.x does not support active per-proxy latency tests; use URLTest history.
• No automatic Forkop/Podkop upgrade.

License

MIT. Forkop and Podkop are separate projects under their own licenses.

Not affiliated

This is an independent, unofficial project. It is not affiliated with, endorsed by or maintained by the Podkop, Forkop or OpenWrt projects.