内容
# clash-verge-mcp
一个**零依赖**的 MCP 服务器，让 AI 助手（Claude Code / Claude Desktop 等）直接控制本机的 **Clash Verge / mihomo**：查看与切换节点、测延迟、切换代理模式、查看连接与规则、更新订阅等。
> 单个文件，无需 `npm install`，无需构建步骤。仅需 Node.js ≥ 18 和 Clash Verge 运行中。
## 工作原理
新版 Clash Verge Rev 默认不开放 TCP 控制器，而是把 mihomo 的 REST API 暴露在 Windows 命名管道 `\\.\pipe\verge-mihomo` 上（Verge 自己也是这样和内核通信的）。本服务器用 Node 内置 `http` 的 `socketPath` 直连该管道，**无需额外开端口**。如果您配置了 TCP `external-controller`，也可以使用它。
服务器自动发现您的 Clash Verge 数据目录，并从其 `config.yaml` 中读取控制器管道名称和 `secret`。
```
Claude (MCP client) ──stdio JSON-RPC──▶ server.mjs ──HTTP over named pipe──▶ mihomo core
```
## 要求
- **Node.js ≥ 18**
- **Clash Verge / Clash Verge Rev** 已安装并运行中（mihomo 内核必须运行）
- 主要在 **Windows** 上测试（命名管道）。macOS/Linux 上如果启用 TCP `external-controller` 也可以（见下文）。
## 安装
```bash
git clone https://github.com/sujushit-code/clash-verge-mcp.git
```
就是这样 - 没有依赖需要安装。
## 配置您的 MCP 客户端
### Claude Code
```bash
claude mcp add clash-verge --scope user -- node /绝对路径/clash-verge-mcp/server.mjs
```
或手动添加到 `~/.claude.json`（用户范围）/ 项目 `.mcp.json` 中：
```json
{
"mcpServers": {
"clash-verge": {
"command": "node",
"args": ["C:/path/to/clash-verge-mcp/server.mjs"]
}
}
}
```
> 在 Windows 上，在路径中使用正斜杠（例如 `C:/Users/you/clash-verge-mcp/server.mjs`），以避免 JSON 反斜杠转义问题。
### Claude Desktop
将相同的块添加到 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置），然后重启应用程序。
重启您的客户端；然后工具以 `mcp__clash-verge__*` 出现。
## 环境变量（均为可选）
服务器在标准 Clash Verge 安装上无需配置即可工作。只有在需要时才覆盖：
| 变量 | 描述 |
|---|---|
| `CLASH_VERGE_DIR` | Clash Verge 数据目录的路径（包含 `config.yaml` 的目录）。如果自动发现失败，请设置此变量。 |
| `CLASH_PIPE` | 要连接的命名管道。默认值：`\\.\pipe\verge-mihomo`。 |
| `CLASH_SECRET` | 控制器密钥。覆盖从 `config.yaml` 读取的值。 |
| `CLASH_USE_TCP` | 设置为 `1` 以使用 TCP `external-controller` 代替管道。 |
| `CLASH_CONTROLLER` | TCP 控制器地址 `host:port`（当 `CLASH_USE_TCP=1` 时使用）。 |
## 工具（22）
| 工具 | 描述 |
|---|---|
| `clash_version` | 内核版本 |
| `get_proxies` / `get_proxy` | 列出所有代理 & 分组 / 获取一个 |
| `select_proxy` | 切换选择器分组的活动节点 |
| `delay_test_proxy` / `delay_test_group` | 延迟测试一个节点 / 整个分组 |
| `get_configs` / `patch_configs` / `set_mode` | 读取配置 / 运行时修补 / 切换规则\|全局\|直接 |
| `get_rules` | 列出活动路由规则 |
| `get_connections` / `close_connection` / `close_all_connections` | 检查 / 关闭连接 |
| `get_proxy_providers` / `update_proxy_provider` / `healthcheck_proxy_provider` | 代理订阅：列出 / 更新 / 健康检查 |
| `get_rule_providers` / `update_rule_provider` | 规则提供者：列出 / 更新 |
| `flush_fakeip` | 清空 fake-ip DNS 缓存 |
| `get_traffic` / `get_logs` | 采样实时流量 / 日志流，时间窗口较短 |
| `clash_request` | 出口：对任意 mihomo 控制器端点的原始请求 |
## 安全
此服务器将您的本地代理控制权暴露给您连接的任何 MCP 客户端。它仅与本地 mihomo 控制器通信，不进行任何出站网络调用。控制器 `secret` 在运行时读取，服务器从未将其写入磁盘。请检查 `server.mjs` - 它是一个可读的单个文件。
## 快速手动测试
```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"clash_version","arguments":{}}}' \
| node server.mjs
```
您应该会看到初始化结果，然后是您的 mihomo 版本。
---
## License
[MIT](./LICENSE)
