podkop-mcp

podkop-mcp

Languages: English · Русский

MCP server for managing [Podkop](https://github.com/itdoginfo/podkop) and [Forkop](https://github.com/ushan0v/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/ /.ssh/router_key", "PODKOP_MCP_KNOWN_HOSTS": "C:/Users/ /.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/ /.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/ /etc/podkop-mcp/backups/ - .uci → uci set/add_list/delete (package restricted to forkop/podkop) → uci commit → /etc/init.d/ 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 contai