Clash Control MCP

A MCP Server that lets AI agents safely read, audit, and manage Clash Verge Rev / Mihomo configuration. v1.0.0-rc.1 — authenticated Clash Verge Adapter writes, recovery inspection, and evidence-driven optimization helpers.

What This Does

Clash Control MCP exposes Clash Verge Rev's configuration and Mihomo's runtime state to AI agents (Codex, ZCode, Claude Code) through the Model Context Protocol. Agents can:

• Detect Clash Verge Rev installation, version, and config paths

• Read Mihomo runtime status (version, mode, ports, connections, traffic)

• List and inspect proxy groups, profiles, and providers

• Audit configuration for issues

• Discover Verge settings and their storage locations

The original v0.1 tools remain read-only. v0.2-A adds two runtime-only operations: allowlisted delay testing and confirmed proxy selection with verification and rollback. It does not modify persistent configuration, DNS, TUN, or system proxy settings.

Related MCP server: Files MCP Server

Core MCP Setup from Source

git clone https://github.com/huaqing0/clash-control-mcp.git
cd clash-control-mcp
npm install
npm run build
npm run setup -- --all

This legacy core-only setup keeps the official Clash Verge App unchanged. It detects the local controller, backs up the selected client configurations, and installs the MCP server into Codex and ZCode. The controller secret is never printed, but it must be stored in each selected client's private MCP config.

Install only one client:

npm run setup -- --codex
npm run setup -- --zcode

The supported Adapter installer below configures TRAE's detected global MCP file; it never creates a project-local .trae/mcp.json. Use that path for Codex, ZCode, or TRAE when testing Profile refresh/activation.

Restart the configured client, then ask it to call clash.capabilities.

Uninstall the managed entries:

npm run setup -- --all --uninstall

Upgrade a source installation by pulling the new code and running the same setup command again. The managed entry is replaced rather than duplicated:

git pull
npm install
npm run setup -- --all

The installer creates timestamped backups beside the Codex and ZCode config files and keeps the resulting files at mode 0600. Because stdio MCP clients must pass the controller secret to the server, the secret is stored in the client's local configuration; never publish or share those files.

If auto-detection is unavailable, provide the values only for the setup process:

CLASH_CONTROLLER_URL=http://127.0.0.1:9097 \
CLASH_CONTROLLER_SECRET='your-secret' \
npm run setup -- --all

Clash Verge Adapter Lifecycle

Profile refresh, activation, and future Verge-memory synchronization require the companion Adapter App. From a source checkout, use the single lifecycle entrypoint (Node.js 20.19.0 or newer):

npm ci
npm run build
npm exec -- clash-control-adapter --help
npm exec -- clash-control-adapter install --help

It provides install, upgrade, verify, uninstall, patch-install, patch-verify, and patch-uninstall. Full installation requires a separately built and validated Adapter .app; it does not download or silently replace Clash Verge. See ADAPTER-INSTALLATION.md for the dry-run-first workflow, supported global client paths, recovery model, and recovery rules. Users of the version-pinned Apple Silicon unsigned patch should follow ADAPTER-PATCH-INSTALLATION.md. The GPL-3.0 Adapter source is maintained separately at huaqing0/clash-verge-adapter.

Build Only

npm install
npm run build

Configure

Set environment variables (see .env.example for reference):

CLASH_CONTROLLER_URL=http://127.0.0.1:9097
CLASH_CONTROLLER_SECRET=your-secret-here
# Optional: Unix socket fallback (auto-detected from Verge if not set)
# CLASH_CONTROLLER_SOCKET=/tmp/verge/verge-mihomo.sock

The secret is in your Clash Verge Rev generated config (clash-verge.yaml), under the secret: key.

Never commit your secret to git. Configure it via MCP env in your agent config or system environment variables.

Run

# Start MCP server (stdio)
npm start

# Or run directly
node dist/index.js

Generic MCP client configuration:

{
  "mcpServers": {
    "clash-control": {
      "command": "node",
      "args": ["/path/to/clash-control-mcp/dist/index.js"],
      "env": {
        "CLASH_CONTROLLER_URL": "http://127.0.0.1:9097",
        "CLASH_CONTROLLER_SECRET": "your-secret"
      }
    }
  }
}

Smoke Test

npm run smoke-test

Validates the safe read-only Mihomo endpoints and writes a local, gitignored API-SMOKE-TEST.json. It may contain machine-specific runtime metadata and must not be published. The reload endpoint remains unverified when no side-effect-free probe is available.

Tools (66 tools)

v0.1 Read-Only Tools (15)

v0.2-A Runtime Control Tools (2)

v0.2-B Runtime Discovery and Ops Tools (6)

v0.3 Config and Recovery Tools (7)

v0.4 Verge Settings Tools (8, capability-gated)

Each setting remains independently capability-gated. On the tested Verge 2.5.1 QA Adapter build, the native settings path performs optimistic concurrency checks, updates Verge memory and persistence, applies Mihomo runtime state, queues GUI refresh, verifies desired/persisted/reported/GUI/ observed evidence, and compensates on failure. Official builds without the Adapter continue to fail closed.

v0.5-A/C Profile & Subscription Tools (6)

Security and capability notes:

• All UID/path inputs are validated by ^[A-Za-z0-9_-]{1,120}$ and resolved with realpath + parent-directory walk. Directory-traversal payloads (.., absolute paths, ., -) are rejected before any filesystem access.

• Inspect payloads are capped (MAX_RULES_RETURNED = 200, DEFAULT_RULES_LIMIT = 50) and paginate via cursor tokens; every layer returns a structured parseStatus (ok / missing / parse_error / not_yaml) with a parseError object — no silent failures.

• Subscription URLs are deeply redacted to scheme://host/*** (path and query stripped) before entering any return payload.

• clash.profiles.refresh distinguishes refreshKind: 'subscription' from Mihomo Proxy/Rule Provider refresh (clash.runtime.refresh_proxy_provider / clash.runtime.refresh_rule_provider). It never fakes REFRESHED — when the authenticated Adapter is unavailable it returns BLOCKED with manual GUI steps and the profileRefresh capability stays false.

Clash Verge Adapter

Profile refresh, activation, persistent Profile writes, synchronized proxy selection, and native Verge settings writes require the companion Adapter build. The Adapter is opt-in, listens only on 127.0.0.1, and requires a per-installation Bearer token. The installer stores that token only in a private 0600 credentials file; clients receive CLASH_VERGE_ADAPTER_TOKEN_FILE, not the token itself. Official Clash Verge builds remain supported for read-only and Mihomo runtime tools; Adapter-owned writes fail closed.

v0.5-B Profile Persistent Write Tools (5, capability-gated)

All five tools remain fail closed unless the authenticated Adapter reports the matching capability for the tested Verge version. The 2.5.1 RC QA build has passed controlled real update-and-restore samples for metadata, Merge YAML, YAML Override, and independent Rules; JavaScript mutation remains blocked.

Security model:

• Owner resolution from profiles.yaml real file and option references; no filename guessing. realpath boundary check prevents symlink traversal.

• Non-reusable nonce binds: target Profile UID, owner UID, owner path, owner fingerprint, chain fingerprint, normalized patch hash, section, ruleset fingerprint, and expiry (5-minute TTL).

• Full transaction: preview → schema validation → optimistic owner fingerprint check → native Adapter write → persistence/runtime verification → commit or compensating restore.

• Dual-layer lock (in-process mutex + cross-process file lock with PID liveness).

• Rules use stable anchors (normalized content + adjacent fingerprints), not line numbers. RULESET_CHANGED_DURING_TRANSACTION aborts on concurrent modification.

• A write returns COMMITTED only after the Adapter verifies the applicable persistence/runtime state and queues GUI refresh; unverified paths never claim success.

v1.0 Optimization Tools (12, read-only orchestration helpers)

Optimizers do not write configuration. They return facts, probes, findings, recommendations, and proposed calls to the existing guarded tools. The calling AI performs one confirmed action at a time, compares identical probes, and invokes the original rollback path immediately on regression.

These helpers are an evidence harness, not a replacement for agent reasoning. They make common routing semantics explicit for less capable models: global and direct modes cannot be mistaken for active rule routing, live connection chains and the current GLOBAL selection are reported separately from static rules, single-candidate groups are identified as lacking group-level failover, and a health-check report distinguishes an unreadable configuration from a verified topology where health checks are not applicable. An agent may still inspect the lower-level MCP facts and form a different recommendation, but every write stays behind the same confirmation, capability, verification, and rollback gates.

v1.1 Verge Preferences Tools (5, capability-gated, fail-closed)

Schema is keyed to real Clash Verge Rev 2.5.1 source (i18n.ts, setting-verge-basic.tsx, pages/_routers.tsx, layout-viewer.tsx, hotkey-viewer.tsx, core/hotkey.rs, config/verge.rs):

• 13 real languages, 5 tray events (Linux unsupported), 5 env types (IMMEDIATE), 8 start pages (with leading /), 3 menu icons, 4 notice positions

• 8 public hotkey functions (open_or_close_dashboard, clash_mode_rule, clash_mode_global, clash_mode_direct, toggle_system_proxy, toggle_tun_mode, entry_lightweight_mode, reactivate_profiles); quit/hide are native internal shortcuts and are NOT in the allowlist

• Accelerator aliases are canonicalized before duplicate/reserved checks; macOS input/window combinations observed in the real desktop environment (Command+Space, Control+Space, and their protected variants) are rejected by both MCP and Adapter

• common_tray_icon removed from the write allowlist (no safe icon asset and verifiable side effect)

Security model (per Codex v1.1 review P0/P1 rectification):

• No fake COMMITTED — Basic/Theme/Layout remain UNVERIFIED until GUI-visible effects are acknowledged; start_page is PENDING_RESTART until the next Clash Verge launch because closing the dashboard only hides and reuses the current WebView. Hotkeys become COMMITTED only when memory, verge.yaml, and the native Tauri registration set all match; incomplete ok=true bodies remain UNVERIFIED.

• Structured 409/429 — 409 + errorCode: "CHANGED" → PREFERENCES_CHANGED (state drift, caller must re-preview, returns REJECTED); 409 without errorCode → TRANSACTION_BUSY (mutation busy, returns BLOCKED); 429 + retryAfterMs → ADAPTER_RATE_LIMITED (returns BLOCKED with retryAfterMs).

• Light confirmation fingerprint — confirm=true for Basic/Theme/Layout must carry the ownerFingerprint returned by a matching, unexpired preview for the identical values. MCP re-reads the strict Adapter snapshot and rejects missing, drifted, changed, or direct-confirm attempts.

• Real ownerFingerprint — Adapter and read-only inspect both use SHA-256 over the exact verge.yaml bytes (first 16 bytes / 32 lowercase hex); the legacy fixed "adapter" placeholder and JSON-object fingerprint are not used for writes.

• Adapter-side deny_unknown_fields DTO — VergePreferencesBody/HotkeysBody reject unknown fields; Adapter independently validates types/enums/lengths/colors/fonts/menu_order/platform/prototype pollution and returns 400 REJECTED before any memory/file/OS modification.

• Compensating rollback re-verification — On failure, the Adapter re-reads memory and persisted state; Hotkeys also re-check the native registration set. A Preferences rollback is ROLLED_BACK only when memory, persisted bytes, native side-effect replay, and GUI-refresh scheduling all succeed; missing evidence remains RECOVERY_REQUIRED. rollbackVerified never relies only on patch_verge(...).is_ok().

• Hotkeys transactional — Adapter saves original mapping/enable/verifiable OS registration set before writing; on partial registration failure it explicitly unregisters the new keys and restores the old set, then re-verifies. If the Tauri global-shortcut API cannot reliably enumerate or verify OS registration, the result is fail-closed UNVERIFIED/ROLLED_BACK/RECOVERY_REQUIRED, never COMMITTED.

The four write tools require authenticated Adapter capability settings.verge-preferences plus the matching fine-grained write capability. Read-only inspect may fall back to local verge.yaml, but never invents confirmation evidence when the real owner bytes are unavailable. macOS/Clash Verge 2.5.1 real-desktop acceptance covered visible Basic/Theme/Layout changes, NEXT_LAUNCH start-page behavior, native hotkey registration, 409/429/BUSY faults, same-call rollback, byte-exact restoration, and unchanged Profile/network state. Synthetic accessibility key events are not treated as proof of a physical global-hotkey callback.

Supported Versions

Security

• Controller credentials are read from the selected client's private managed config or process environment; Adapter tokens are read from the private credentials file referenced by CLASH_VERGE_ADAPTER_TOKEN_FILE

• All outputs are redacted (tokens, passwords, subscription URLs)

• No arbitrary shell, file, HTTP, or API access

• See SECURITY.md for details

Roadmap

See ROADMAP.md.

License

MIT