mihomo-party-mcp

一个 MCP server，让 AI 客户端（Codex、Claude Code 等）用自然语言管理本机的 clash / mihomo 代理前端：

• 增删分流规则（某域名走代理还是直连）

• 列出/切换订阅 profile

• 切换代理节点组的选中节点

• reload 使改动生效

纯 Node 内置模块，无第三方依赖，跨平台自动探测前端。

支持的前端

也支持环境变量覆盖：MIHOMO_PARTY_DIR、MIHOMO_CONTROLLER(host:port)、MIHOMO_SECRET。

控制面来自 mihomo 核心的 REST API（external-controller，默认 127.0.0.1:9090，secret 从前端配置自动读取）。

Related MCP server: Clash Control MCP

安装

git clone https://github.com/<you>/mihomo-party-mcp.git
cd mihomo-party-mcp
node install.mjs --force        # 注册 MCP 到 ~/.codex 与 ~/.claude，并注册 agent 角色

--force 会同时注册三件事：Codex/Claude 的 MCP server、以及 Codex 的 mihomo_party 多 agent 角色。 若只想注册 agent 角色，单独运行 node install.mjs --agent。

或手动在客户端配置里加（见下）。

客户端配置

Codex (~/.codex/config.toml)

[mcp_servers.mihomo_party]
command = "/usr/local/bin/node"
args = ["/absolute/path/to/mihomo-party-mcp/server.mjs"]

Claude Code (~/.claude.json)

{ "mcpServers": { "mihomo_party": { "command": "/usr/local/bin/node", "args": ["/absolute/path/to/mihomo-party-mcp/server.mjs"] } } }

作为 Codex agent 角色使用

仓库内置 agents/mihomo-party.toml，是一个 Codex 多 agent 角色（依赖上面的 mihomo_party MCP）。 注册后可在 Codex 里把代理管理任务委派给它（如 /agent mihomo_party 或在工作流中作为子 agent）。

安装脚本 install.mjs --agent 会：

1. 复制 agents/mihomo-party.toml 到 ~/.codex/agents/；

2. 在 ~/.codex/config.toml 开启 [features] multi_agent = true；

3. 追加 [agents.mihomo_party] 段指向该角色文件。

对应 config.toml 片段：

[features]
multi_agent = true

[agents]
max_threads = 6
max_depth = 1

[agents.mihomo_party]
description = "Clash Party / mihomo-party 代理管理 agent（依赖 mihomo_party MCP）。"
config_file = "agents/mihomo-party.toml"

规则拆分建议（全局 vs profile）

Clash Party 的覆写分为两类，别混淆：

• profile override：在 profile.yaml 里被某个 profile 的 override: 引用，只对那一个 profile 生效。

• global override：在 override.yaml 里 global: true，对所有 profile 生效。

典型拆分：

1. 90-global-rules.yaml（global: true）：放所有 profile 共享的规则，如 Gmail 收发分流、微信直连、局域网直连、兜底 MATCH。

2. 1930f207b66.yaml（global: false）：放当前激活 profile 的个性化分流，保留但应去重。

注意：

• 改 override 后重启 app 才会重新生成 work/config.yaml；reload_config 只重载内核当前配置，不一定重新合并 override。

• 具体域名规则（如 DOMAIN,imap.gmail.com）必须排在更宽泛规则（如 DOMAIN-SUFFIX,google.com）之前，否则被提前命中。

• 不要删除含 +proxies / +proxy-groups 的 override 段，规则可能依赖其中的 代理出口 / 直连出口 等出口名。

本仓库的 agent 角色内置上述经验，可直接把“规则去重 / 拆全局 / 调 Gmail 分流”等任务交给它。

工作原理

• 规则来源：写入前端的 override / profile 文件（持久），而非只改运行配置。

• 规则顺序：clash 规则先匹配先生效。新增具体域名规则会插到 override +rules: 段最前面， 以免被订阅内的 DOMAIN-SUFFIX,google.com 等通用后缀规则抢先。

• 生效：mihomo-party 改完调 reload_config（核心重载 work/config.yaml）；clash-verge 通过 switch_profile 或 UI 触发。

工具

示例

让 Gmail 收发分流：imap 走代理、smtp 直连（避免 SMTP 被代理断开）。

让 agent 执行（或直接调用工具）：

add_rules rules=["DOMAIN,imap.gmail.com,代理出口","DOMAIN,smtp.gmail.com,DIRECT"]
reload_config

注意：因为订阅里通常有 DOMAIN-SUFFIX,google.com,代理出口，smtp.gmail.com 必须排在它之前才会直连——本 server 的 add_rules 已自动置顶。

安全

• 仅本地通信（127.0.0.1）。

• 所有改动写入你机器上的前端配置文件，建议改动前备份（server 不改订阅 URL、不改 secret）。

• 不联网、不收集数据。

License

MIT