podkop-mcp

podkop-mcp

语言： English · Русский

用于通过 SSH 管理 OpenWrt 上 Podkop 和 Forkop 的 MCP 服务。

无需再手动编辑 UCI、牢记 uci add_list 陷阱，或向 PowerShell 传递 base64 编码的脚本。让 MCP 客户端添加域名、列出分区、检查实时连接、重新加载服务并回滚错误更改——内置试运行、备份和脱敏功能。

状态：Alpha。已针对 Forkop 1.0.5 和 Forkop 2.0.0（OpenWrt 25.12.6）进行实时只读测试。写入／应用流程已在运行真实 Forkop 2.0.0 和 Podkop 0.7.24 的临时 OpenWrt Docker 容器中验证。后端架构每隔 PODKOP_MCP_PROFILE_TTL 秒（默认 30 秒）重新验证。

为什么

手动管理 Podkop/Forkop 容易出错：

• Forkop 1.x 将域名存储为一个以空格分隔的字符串（section.domain）。 使用一次 uci add_list 就会将其变成精确匹配的 domain 列表，子域名也会在不知情的情况下停止路由。
• Forkop 2.x 使用包含 # 注释的多行 section.destinations 文本。
• Podkop 使用真正的 UCI 列表（section.user_domains）。
• Forkop 异步重新加载；必须检测重新加载失败并回滚。
• 订阅 URL 和代理字符串都是机密，最终会出现在日志中。

与直接运行在路由器上的 MCP 服务不同，podkop-mcp 运行在管理员的计算机上，通过 SSH 与 OpenWrt 通信，并理解 Podkop/Forkop 的语义：试运行、备份、回滚和机密脱敏。所有这些功能都封装在类型化 MCP 工具后面。

功能

• SSH 传输，可从 MCP 参数提供密钥：密钥文件、内联 base64/PEM，或 ~/.ssh/config 别名。支持主机密钥验证、保持连接和超时设置。
• 后端检测：Forkop 1.x、Forkop 2.x、Podkop；根据已安装的 CLI 确定功能。
• 通过 ubus call uci get JSON 和用于写入的 uci 实现完整的 UCI 访问。可读取或更改任意选项；软件包范围限制为 forkop／podkop。
• 域名操作，保留后端格式：添加／删除／替换、搜索覆盖范围、根据实时连接建议未覆盖的主机、检查 FakeIP。
• 分区：列出、检查、创建、更新、启用／禁用、删除，并级联删除子订阅／URLTest 项目。
• 订阅和代理组：列出、添加、删除、更新、测试延迟、选择代理（Forkop 2.x）。
• 监控：服务／系统状态、运行状况检查、日志、实时连接、流量速率、代理延迟。
• 安全性：修改类工具默认使用试运行；apply=true 会创建路由器端备份、提交 UCI、重新加载并验证。失败时会自动恢复备份。PODKOP_MCP_READ_ONLY=1 会阻止所有写入操作。
• 默认对机密进行脱敏：订阅 URL、proxy_string、密钥、令牌。导出原始数据需要 reveal_secrets=true。
• 双语文档（英语／俄语）和 CI。

支持矩阵

功能	Forkop 1.x	Forkop 2.x	Podkop
UCI 包	forkop	forkop	podkop
域名选项	domain（字符串）	destinations（多行）	user_domains（列表）
社区列表	是	是	是
规则集	否	是	是
Clash API	action CLI	HTTP CLI	action CLI
代理运行时选择	—	是	—
只读监控	是	是	是

安装

要求：

• Python 3.10+（CI 使用 3.10 至 3.14 进行测试）
• 已安装 Forkop 或 Podkop 的 OpenWrt 路由器
• 可通过 SSH 密钥访问路由器

从 PyPI 安装：

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

从源码安装：

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 .

配置 MCP 客户端（Claude Desktop、Cursor、DSH 等）：

{
  "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"
      }
    }
  }
}

或者使用现有的 ~/.ssh/config 别名：

"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"
}

主机密钥策略默认为 reject。请先将路由器密钥添加到 known_hosts （例如，通过正常的 ssh 登录）。对于新路由器，accept-new 是一次性的 TOFU 便利选项；它无法防范首次连接时的 MITM 攻击。

向模型提出请求：

• “运行 podkop_doctor 并显示后端版本。”
• “将 example.com 和 cdn.example.com 添加到 main；先向我显示差异。”
• “列出包含域名数量的分区。”
• “实时连接中的哪些主机未被任何分区覆盖？”
• “显示最近 2 秒的流量和排名靠前的客户端。”
• “禁用 youtube 分区并重新加载。”

文档

• 工具参考 · Справочник инструментов
• 架构 · Архитектура
• 兼容性 · Совместимость
• 故障排除 · Диагностика
• 在 OpenWrt Docker 中测试 · Тестирование в Docker
• 安全 · Безопасность
• 安全策略，贡献指南

写入操作的工作方式

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

不会通过由用户输入构建的 shell 字符串执行命令；值会使用 shlex 进行 shell 引用，脚本则通过 stdin 发送给 sh。路径会经过验证；路由器上不需要 base64 applet。

工具概览

分组	工具
系统	podkop_doctor、podkop_status、podkop_system_info、podkop_health、podkop_logs、podkop_cli、podkop_core_features、podkop_import_check、podkop_installer_status、podkop_installer_log
配置	podkop_config_get、podkop_config_export、podkop_option_get/set/delete、podkop_backup_create/list/restore
分区	podkop_sections_list、podkop_section_get/create/update/delete/enable、podkop_tunnel_create、podkop_child_create
域名	podkop_domains_list/add/remove/replace/find/suggest、podkop_domain_check
列表	podkop_community_lists_get/update
连接	podkop_connections_config、podkop_subscription_add/delete/update、podkop_proxies_list、podkop_proxy_select/test
监控	podkop_monitor_snapshot、podkop_connections_live、podkop_traffic
服务	podkop_service_action、podkop_lists_update

完整参考：docs/tools.md。

配置参考

变量	默认值	含义
PODKOP_MCP_SSH_HOST	—	路由器地址
PODKOP_MCP_SSH_PORT	22	SSH 端口
PODKOP_MCP_SSH_USER	root	SSH 用户
PODKOP_MCP_SSH_KEY_PATH	—	私钥路径
PODKOP_MCP_SSH_KEY	—	内联私钥（PEM）
PODKOP_MCP_SSH_KEY_B64	—	内联密钥，base64 编码
PODKOP_MCP_SSH_KEY_PASSPHRASE	—	密钥口令
PODKOP_MCP_SSH_PASSWORD	—	使用密码而非密钥（机密：通过环境变量传递，切勿提交）
PODKOP_MCP_SSH_CONFIG_HOST	—	~/.ssh/config 中的别名
PODKOP_MCP_KNOWN_HOSTS	~/.ssh/known_hosts	主机密钥文件
PODKOP_MCP_HOST_KEY_POLICY	reject	reject、accept-new、ignore
PODKOP_MCP_CONNECT_TIMEOUT	8	SSH 连接超时时间，单位为秒
PODKOP_MCP_COMMAND_TIMEOUT	45	命令超时时间，单位为秒
PODKOP_MCP_BACKEND	auto	auto、forkop 或 podkop；必须已安装所请求的 CLI
PODKOP_MCP_READ_ONLY	0	阻止所有写入操作
PODKOP_MCP_BACKUP_DIR	/etc/podkop-mcp/backups	路由器端备份
PODKOP_MCP_BACKUP_KEEP	30	保留的备份数量
PODKOP_MCP_MAX_OUTPUT_BYTES	200000	捕获的命令输出上限，单位为字节
PODKOP_MCP_LOG_LEVEL	INFO	服务在 stderr 上的日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）
PODKOP_MCP_PROFILE_TTL	30	后端配置文件与路由器重新验证前的间隔秒数
PODKOP_MCP_TARGETS	—	包含多台路由器的 JSON
PODKOP_MCP_CONFIG	—	包含多台路由器的 JSON 文件路径；优先级高于 PODKOP_MCP_TARGETS 和单路由器变量
PODKOP_MCP_TARGET_NAME	router	由 PODKOP_MCP_SSH_HOST / PODKOP_MCP_SSH_CONFIG_HOST 定义的单台路由器名称；使用 JSON 目标列表时会忽略

要管理多台路由器，请将它们放入 JSON 文件，并将 PODKOP_MCP_CONFIG 指向该文件：

{
  "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"
}

当工具调用未传入 target 时，会使用 default_target 路由器（若省略，则使用第一台）；传入 "target": "office" 即可使用另一台路由器。PODKOP_MCP_TARGET_NAME 不会从此文件中选择目标，它只为由 PODKOP_MCP_SSH_HOST / PODKOP_MCP_SSH_CONFIG_HOST 定义的单台路由器命名。

测试

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

对于真实的 SSH/UCI/应用路径，有一个 OpenWrt Docker 容器： 真实的 openwrt/rootfs 用户空间、真实的 ubus/rpcd/dropbear/uci，并为 Forkop CLI/init 提供存根（不包含 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

这是一个容器，不是 VM：它与主机共用内核。完整的 VM 说明和限制见 docs/testing.md。实时测试绝不会写入生产路由器；写入操作会在 Docker 容器和模拟传输中进行测试。

限制

• MCP 传输方式为 stdio；不涉及 SSE/HTTP。
• 目前尚未开放对分区重新排序的支持（UCI 顺序即文件顺序）；如有需要，请使用导出/编辑
  • podkop_config_export。
• Podkop 订阅处理尽力而为；当前活跃目标为 Forkop。
• Forkop 1.x 不支持主动进行逐代理延迟测试；请使用 URLTest 历史记录。
• 不会自动升级 Forkop/Podkop。

许可证

MIT。Forkop 和 Podkop 是独立项目，遵循各自的许可证。

无关联关系

这是一个独立的非官方项目，与 Podkop、Forkop 或 OpenWrt 项目无关联，未获其认可，也不由其维护。