mcp-server-clash-verge

MCP (Model Context Protocol) server for Clash Verge Rev / Mihomo (Clash Meta). Lets Claude Code and other MCP-compatible AI agents control your proxy — switch nodes, change modes, reload config, test latency — directly from conversation.

中文文档

One-Click Install

Tell Claude Code this one sentence:

Help me install https://raw.githubusercontent.com/IS5416/mcp-server-clash-verge/main/SETUP.md

Claude will auto-detect your platform, install the package, configure ~/.claude.json, and verify everything. No manual steps. No environment variables. Restart Claude Code and you're done.

Why

When Claude Code hits network errors behind a proxy, you don't want to switch to the Clash Verge GUI, find a faster node, then tell Claude "try again." You want Claude to fix it itself.

This MCP server gives Claude 7 tools to manage your Mihomo proxy autonomously.

Requirements

• Clash Verge Rev (or any Mihomo-based client) with External Controller enabled
• Python ≥ 3.10

Manual Install

1. Install the package

pip install mcp-server-clash-verge

Or from source:

git clone https://github.com/IS5416/mcp-server-clash-verge.git
cd mcp-server-clash-verge
pip install -e .

2. Configure Claude Code

Edit ~/.claude.json and add to the mcpServers object:

"clash-verge": {
  "command": "python",
  "args": ["-m", "mcp_server_clash_verge"],
  "env": {},
  "type": "stdio"
}

If you have uv installed:

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

No env block needed. The MCP server auto-detects Clash Verge Rev's configuration file on Windows, macOS, and Linux.

Restart Claude Code.

3. Try It

"List all my proxy nodes."
"Switch to HK-01."
"I'm getting network errors, find a fast node and switch to it."

Tools

Tool	Description
list_proxies	All proxy groups, nodes, current selection, and delay
switch_proxy	Switch a proxy group to a specific node
get_proxy_mode	Current mode: rule / global / direct
set_proxy_mode	Set mode: rule / global / direct
test_proxy_delay	Test latency of a specific node (milliseconds)
reload_config	Force reload Mihomo configuration from disk
list_rules	Show active routing rules

Configuration

Zero config by default. The server auto-detects Clash Verge Rev on all platforms:

Platform	Config path
Windows	%APPDATA%\io.github.clash-verge-rev.clash-verge-rev\config.yaml
macOS	~/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev/config.yaml
Linux	~/.config/io.github.clash-verge-rev.clash-verge-rev/config.yaml

Override (optional)

Set environment variables in ~/.claude.json if you use a non-standard Clash client:

"clash-verge": {
  "command": "python",
  "args": ["-m", "mcp_server_clash_verge"],
  "env": {
    "MIHOMO_API_URL": "http://127.0.0.1:9097",
    "MIHOMO_API_SECRET": "your-secret"
  },
  "type": "stdio"
}

Variable	Default	Description
MIHOMO_API_URL	auto-detected	Mihomo external controller address
MIHOMO_API_SECRET	auto-detected	API secret from Clash Verge settings

Use Cases

• Claude Code hits proxy timeout during web scraping/search → automatically switch to a low-latency node and retry
• Need temporary global proxy → set_proxy_mode global, switch back to rule mode when done
• After subscription update → reload_config to refresh without touching the GUI
• Debug routing issues → list_rules to check current rules match expectations

Security

• The MCP server communicates with Claude Code exclusively via stdio — it opens no network ports
• Mihomo API secret is read from your Clash Verge config file, never hardcoded or logged
• All operations are local to your Mihomo instance — no data is sent externally

License

MIT