Content
# clash-verge-mcp
A **zero-dependency** [MCP](https://modelcontextprotocol.io) server that lets an AI agent (Claude Code, Claude Desktop, etc.) control your local **[Clash Verge](https://github.com/clash-verge-rev/clash-verge-rev) / mihomo** instance — list and switch proxies, run latency tests, change the proxy mode, inspect connections and rules, update providers, and more.
> Single file, no `npm install`, no build step. Just Node.js ≥ 18 and Clash Verge running.
## How it works
Recent Clash Verge Rev builds **do not expose the mihomo controller over TCP** by default. Instead the REST API is served over a **Windows named pipe** (`\\.\pipe\verge-mihomo`) — which is exactly how the Verge desktop app talks to its own core. This server connects to that pipe using Node's built-in `http` module via the `socketPath` option, so **no extra port needs to be opened**. If you've configured a TCP `external-controller`, it can use that too.
The server auto-discovers your Clash Verge data directory and reads the controller pipe name and `secret` from its `config.yaml`.
```
Claude (MCP client) ──stdio JSON-RPC──▶ server.mjs ──HTTP over named pipe──▶ mihomo core
```
## Requirements
- **Node.js ≥ 18**
- **Clash Verge / Clash Verge Rev** installed and running (the mihomo core must be up)
- Primarily tested on **Windows** (named pipe). macOS/Linux work if you enable a TCP `external-controller` (see below).
## Install
```bash
git clone https://github.com/sujushit-code/clash-verge-mcp.git
```
That's it — there are no dependencies to install.
## Configure your MCP client
### Claude Code
```bash
claude mcp add clash-verge --scope user -- node /absolute/path/to/clash-verge-mcp/server.mjs
```
Or add it manually to `~/.claude.json` (user scope) / a project `.mcp.json`:
```json
{
"mcpServers": {
"clash-verge": {
"command": "node",
"args": ["C:/path/to/clash-verge-mcp/server.mjs"]
}
}
}
```
> On Windows, use forward slashes in the path (e.g. `C:/Users/you/clash-verge-mcp/server.mjs`) to avoid JSON backslash-escaping headaches.
### Claude Desktop
Add the same block to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart the app.
Restart your client; the tools then appear as `mcp__clash-verge__*`.
## Environment variables (all optional)
The server works with zero configuration on a standard Clash Verge install. Override only if needed:
| Variable | Description |
|---|---|
| `CLASH_VERGE_DIR` | Path to the Clash Verge data dir (the one containing `config.yaml`). Set this if auto-discovery fails. |
| `CLASH_PIPE` | Named pipe to connect to. Default: `\\.\pipe\verge-mihomo`. |
| `CLASH_SECRET` | Controller secret. Overrides the value read from `config.yaml`. |
| `CLASH_USE_TCP` | Set to `1` to use the TCP `external-controller` instead of the pipe. |
| `CLASH_CONTROLLER` | TCP controller address `host:port` (used when `CLASH_USE_TCP=1`). |
## Tools (22)
| Tool | Description |
|---|---|
| `clash_version` | Core version |
| `get_proxies` / `get_proxy` | List all proxies & groups / get one |
| `select_proxy` | Switch the active node of a selector group |
| `delay_test_proxy` / `delay_test_group` | Latency test one node / a whole group |
| `get_configs` / `patch_configs` / `set_mode` | Read config / patch at runtime / switch rule\|global\|direct |
| `get_rules` | List active routing rules |
| `get_connections` / `close_connection` / `close_all_connections` | Inspect / close connections |
| `get_proxy_providers` / `update_proxy_provider` / `healthcheck_proxy_provider` | Proxy subscriptions: list / update / health-check |
| `get_rule_providers` / `update_rule_provider` | Rule providers: list / update |
| `flush_fakeip` | Flush the fake-ip DNS cache |
| `get_traffic` / `get_logs` | Sample the live traffic / log stream for a short window |
| `clash_request` | Escape hatch: raw request to any mihomo controller endpoint |
## Security
This server exposes control of your local proxy to whatever MCP client you connect it to. It talks only to the local mihomo controller and performs no outbound network calls of its own. The controller `secret` is read at runtime and never written to disk by this server. Review `server.mjs` — it's a single, readable file.
## Quick manual test
```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
```
You should see the initialize result followed by your mihomo version.
---
## 中文说明
一个**零依赖**的 MCP 服务器，让 AI 助手（Claude Code / Claude Desktop 等）直接控制本机的 **Clash Verge / mihomo**：查看与切换节点、测延迟、切换代理模式、查看连接与规则、更新订阅等。
**原理**：新版 Clash Verge Rev 默认不开放 TCP 控制器，而是把 mihomo 的 REST API 暴露在 Windows 命名管道 `\\.\pipe\verge-mihomo` 上（Verge 自己也是这样和内核通信的）。本服务器用 Node 内置 `http` 的 `socketPath` 直连该管道，**无需额外开端口**。启动时自动探测 Clash Verge 数据目录并从 `config.yaml` 读取管道名与 `secret`。
**要求**：Node.js ≥ 18；Clash Verge 已安装且正在运行；主要在 Windows 上测试（命名管道），macOS/Linux 需启用 TCP `external-controller`。
**安装**：`git clone` 本仓库即可，无需 `npm install`。
**接入 Claude Code**：
```bash
claude mcp add clash-verge --scope user -- node /绝对路径/clash-verge-mcp/server.mjs
```
或手动写入 `~/.claude.json`（见上方 JSON 示例，Windows 路径建议用正斜杠）。重启客户端后，工具以 `mcp__clash-verge__*` 出现。
环境变量、工具列表见上方英文表格。
## License
[MIT](./LICENSE)
