clash-verge-mcp-pro

全面接管 Clash Verge Rev / Mihomo 的 MCP 服务器(二开自 mcp-server-clash-verge)。

相比原版的改进

问题	原版	本项目
传输方式	仅 TCP HTTP(Clash Verge 默认不开,直接连不上)	自动适配 Unix Socket / Named Pipe / TCP
SDK 兼容	旧低阶 API,新版 mcp SDK 下无法启动	基于 mcp SDK 2.x MCPServer
规则修改	只读	增/删/屏蔽规则,持久化 + 热重载
配置生成	无	完整复刻 Clash Verge enhance 链(SeqMap 卡片 → 模板合并 → 内置守卫 → TUN → DNS → 全局/订阅级 Merge+Script → 权威字段恢复 → 无效引用清理)
JS 脚本	不支持	内置 quickjs 引擎执行 Script 卡片
工具数量	7	58

架构

┌─ 运行时层 mihomo_* ──→ Mihomo 外部控制器(unix socket / TCP 自动检测)
│   节点切换 / 模式 / 连接管理 / providers / DNS 查询 / 缓存清理 / 核心重启
│
└─ 文件层 verge_* ──→ ~/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev/
    profiles.yaml 订阅切换 · rules/proxies/groups 卡片增删改 ·
    Merge.yaml 全局合并 · verge.yaml 应用设置 · dns_config.yaml ·
    enhance 链重新生成 → PUT /configs {path} 热重载核心

关键设计:生成的配置写入独立文件 clash-verge-mcp.yaml,不覆盖 Clash Verge 自己的 clash-verge.yaml,与 UI 双向兼容(UI 下次重新生成时读取的是同一份 profiles 源文件)。

安装

🚀 一句话安装(推荐)

把这句话贴给你的 AI Agent(Claude Code / Cursor / AionUi 等),它会自动完成全部安装配置:

帮我安装 clash-verge-mcp-pro 这个 MCP:读取 https://raw.githubusercontent.com/cdxiaodong/clash-verge-mcp-pro/main/SETUP.md 并严格按步骤执行,装完验证能连上我本机的 Clash Verge,再告诉我怎么用。

手动安装

方式一:PyPI(零安装)

uvx clash-verge-mcp-pro   # uvx 自动从 PyPI 拉取运行

方式二:源码

git clone https://github.com/cdxiaodong/clash-verge-mcp-pro.git
cd clash-verge-mcp-pro && uv sync

MCP 配置(Claude Code ~/.claude.json / AionUi / Cursor 等):

{
  "mcpServers": {
    "clash-verge-pro": {
      "command": "uvx",
      "args": ["clash-verge-mcp-pro"],
      "type": "stdio"
    }
  }
}

源码方式则把 args 换成:["run", "--directory", "<项目绝对路径>", "clash-verge-mcp-pro"],command 改为 uv。

工具一览(58 个)

运行时层 — 基础

• mihomo_status / mihomo_restart_core / mihomo_upgrade_core
• mihomo_list_proxies / mihomo_switch_proxy / mihomo_test_delay / mihomo_test_group_delay / mihomo_unfix_proxy
• mihomo_get_configs / mihomo_patch_configs / mihomo_reload_config
• mihomo_list_rules
• mihomo_list_connections / mihomo_close_connection / mihomo_close_all_connections
• mihomo_list_providers / mihomo_update_provider / mihomo_healthcheck_provider
• mihomo_dns_query / mihomo_flush_cache

运行时层 — 实时流与自动化

• mihomo_recent_logs(WS 采集核心日志,排障利器)
• mihomo_traffic_snapshot / mihomo_memory_snapshot
• auto_select_fastest(测速 → 切最快节点 → 断旧连接,一句话完成)

文件层 — 规则与订阅

• verge_add_rules / verge_remove_rules / verge_list_rule_overrides ← 规则增删改
• verge_add_subscription / verge_update_subscription / verge_subscription_info(流量/到期监控)
• verge_list_profiles / verge_switch_profile / verge_read_profile

文件层 — 节点/组/规则集

• verge_add_proxies(任意协议自定义节点)
• verge_add_group / verge_remove_group
• verge_add_ruleset / verge_remove_ruleset(ACL4SSR 等第三方规则集)

文件层 — 配置与调试

• verge_get_merge / verge_update_merge
• verge_get_settings / verge_patch_settings
• verge_get_dns_config / verge_save_dns_config
• verge_preview_config / verge_apply_config
• verge_trace_domain(模拟规则匹配,查"为什么这个域名没走代理")
• verge_check_rules(重复规则/不可达规则体检)

安全网

• verge_backup / verge_list_backups / verge_rollback(所有破坏性操作自动先备份)

场景与审计

• verge_save_scene / verge_apply_scene / verge_list_scenes / verge_delete_scene(模式+各组节点选择+规则卡片的一键场景切换,如"游戏模式")
• verge_audit_routing(批量域名分流审计:每个域名命中哪条规则、走哪个出口)
• verge_diff(apply 前预览:将生成的配置 vs 运行中的配置)
• mihomo_update_geo(在线更新 geoip/geosite/mmdb)

功能实测截图

以下截图来自与 AI 助手(AionUi / Claude)的一次真实会话,所有数据均为线上实测:

核心状态 / 内存 / 实时流量 — 自动探测 Unix Socket 直连核心:

代理组全量读取 — 12 个组的类型、当前选择、节点延迟:

节点延迟实测 — HTTP 实测 123ms,非缓存值:

规则追踪 — 一句话回答"google.com 走哪条路?命中哪条规则?":

订阅流量监控 — 已用 / 剩余 / 到期时间(订阅链接已脱敏):

活动连接监控 — 哪个进程、访问什么、走哪条链、代理还是直连:

实战排障案例 — ToDesk 无法登录,用 mihomo_recent_logs + mihomo_list_connections 组合拳 3 分钟排除代理嫌疑、定位到系统服务未启动:

环境变量(可选)

• MIHOMO_API_URL:覆盖控制器地址,支持 unix:///path/to.sock 或 http://host:port
• MIHOMO_API_SECRET:覆盖 API 密钥
• CLASH_VERGE_HOME:覆盖数据目录(多客户端适配;缺省自动探测 Clash Verge Rev → 旧版 → ClashX 路径)

已知边界

• 切换订阅/修改 verge.yaml 后,Clash Verge UI 状态不会实时同步(应用重启后一致);核心侧立即生效
• 修改 verge.yaml 中系统代理/TUN 等应用级开关,建议随后调用 verge_apply_config,部分需重启应用
• mihomo_upgrade_core 仅 alpha 内核支持
• 规则追踪不评估逻辑规则(AND/OR/NOT)与 GEOIP/GEOSITE(需要 mmdb/geosite 数据)

发布 PyPI(待办)

uv build
uv publish --token <pypi-token>   # 需要你自己注册 PyPI 账号