Clash Control MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Clash Control MCP list my proxy groups"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Clash Control MCP
English | 简体中文
An 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. The supported end-user product includes the authenticated Adapter; Core-only setup is retained only as a degraded recovery/development path and is not a release installation choice. 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: mijia-fast
Full Installation (Adapter Required)
The v1.0.0-rc.1 end-user release supports only macOS Apple Silicon (arm64),
official Clash Verge Rev 2.5.1, and Node.js 20.19.0 or newer. The npm
package deliberately has no Core-only setup command.
Install the MCP and its verified lifecycle installer:
npm install --global clash-control-mcp@nextDownload the matching Adapter patch from the
v1.0.0-rc.1GitHub Release, or use GitHub CLI:
gh release download v1.0.0-rc.1 \
--repo huaqing0/clash-control-mcp \
--pattern 'Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64.zip'
unzip Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64.zipRun the zero-write preflight while Clash Verge is still open:
clash-control-adapter patch-install \
--patch-package "$PWD/Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64" \
--dry-runQuit Clash Verge completely, install the full product, then restart Clash Verge and the configured MCP clients:
clash-control-adapter patch-install \
--patch-package "$PWD/Clash-Verge-2.5.1-Adapter-Unsigned-macos-arm64" \
--clients codex,zcode,trae
clash-control-adapter patch-verifyThe installer detects the local Controller, creates verifiable backups, writes
the managed client entries, and never prints the Controller secret or Adapter
token. After verification, call clash.capabilities; the Adapter handshake
must be authenticated and available for the installation to be accepted.
Clash Verge Adapter Lifecycle
The Adapter is part of the supported product, not an optional feature tier. From a source checkout, maintainers use the same lifecycle entrypoint:
npm ci
npm run build
npm exec -- clash-control-adapter --help
npm exec -- clash-control-adapter install --helpIt provides install, upgrade, verify, uninstall, patch-install,
patch-verify, and patch-uninstall. Installation requires an explicitly
downloaded, version-pinned release patch or a separately built and validated
Adapter .app; npm installation alone never replaces 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.
Upgrades reuse the exact client set and paths from a VERIFIED acceptance
lineage; legacy Adapter installs without that lineage must restore the official
App from a trusted backup and perform a fresh install.
The GPL-3.0 Adapter source is maintained separately at
huaqing0/clash-verge-adapter.
Build Only
npm install
npm run buildConfigure
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.sockThe 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.jsSource-checkout 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-testValidates 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)
Tool | Description |
| Environment capabilities (must call first) |
| Comprehensive diagnostics |
| Verge detection: version, paths, compatibility |
| Read Verge network/runtime settings |
| Get config directories and paths |
| Get currently active profile |
| List Verge profiles (summarized and paginated) |
| Inspect a specific profile by UID |
| Mihomo runtime config (from API) |
| Generated Verge config summary with a safe section allowlist |
| Verge persistent config (from file) |
| Audit configuration for issues |
| Mihomo runtime status summary |
| List policy groups (summarized and paginated) |
| Get one policy group's safe, paginated candidate names and runtime health details |
v0.2-A Runtime Control Tools (2)
Tool | Description |
| Test proxy delay with multiple samples, returns median and jitter |
| Switch proxy in Selector group with verification and auto-rollback |
v0.2-B Runtime Discovery and Ops Tools (6)
Tool | Description |
| List safe proxy Provider names and summaries |
| List safe rule Provider names and summaries |
| List redacted connection summaries and IDs |
| Refresh a proxy provider (per-provider lock, confirmed, verified) |
| Refresh a rule provider (per-provider lock, confirmed, verified) |
| Close a specific connection by ID (close-all NOT supported) |
v0.3 Config and Recovery Tools (7)
Tool | Description |
| Create an isolated in-memory workspace |
| Preview a semantic, redacted diff |
| Fail-closed schema, fingerprint, and risk validation |
| Apply a validated low-risk workspace through the authenticated Adapter, then run file/runtime/network/GUI health checks with automatic rollback |
| Restore a persisted transaction snapshot |
| Verify a persisted PENDING_RESTART after Verge restart |
| Read durable transaction/recovery state without modifying manifests or snapshots |
v0.4 Verge Settings Tools (8, capability-gated)
Tool | Description |
| Set unified delay through the guarded settings transaction path |
| Set Mihomo log level |
| Set IPv6 state |
| Strategic-merge the DNS kernel block |
| Configure the mixed proxy port |
| Configure LAN access with strong confirmation |
| Strategic-merge the TUN kernel block with strong confirmation |
| Configure Verge connection cleanup through the native Adapter settings path |
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)
Tool | Description |
| Inspect a Verge profile's full chain: base profile, merge layer, override/script layer, rule layer; with per-layer fingerprint, parse status, and redacted subscription URL |
| Inspect a Merge profile's raw structure, fingerprint, and summary |
| Inspect an Override (Script) profile; Script files are fingerprinted by raw content ( |
| Inspect a profile's rule list with stable rule IDs, pagination (default 50, hard cap 200), and rule-level fingerprints |
| Refresh a remote subscription through the authenticated local Clash Verge Adapter. Local profiles return |
| Activate a Profile through Clash Verge itself. Strong two-step nonce confirmation, active-Profile drift detection, and post-operation verification are mandatory because network routing may change |
Security and capability notes:
All UID/path inputs are validated by
^[A-Za-z0-9_-]{1,120}$and resolved withrealpath+ 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 viacursortokens; every layer returns a structuredparseStatus(ok/missing/parse_error/not_yaml) with aparseErrorobject — no silent failures.Subscription URLs are deeply redacted to
scheme://host/***(path and query stripped) before entering any return payload.clash.profiles.refreshdistinguishesrefreshKind: 'subscription'from Mihomo Proxy/Rule Provider refresh (clash.runtime.refresh_proxy_provider/clash.runtime.refresh_rule_provider). It never fakesREFRESHED— when the authenticated Adapter is unavailable it returnsBLOCKEDwith manual GUI steps and theprofileRefreshcapability staysfalse.
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. Installation verification first challenges the service with
an invalid token, then verifies that the listener is the current user's
/Applications/Clash Verge.app executable before sending the real token.
v0.5-B Profile Persistent Write Tools (5, capability-gated)
Tool | Description |
| Update non-sensitive profile metadata in |
| Update a Merge YAML file with a strategic merge patch. Owner resolved from the target Profile's |
| Update a YAML Override. JavaScript Script files ( |
| Add rules to a section ( |
| Remove rules by fingerprint from a section of the Rules owner file. Each fingerprint must uniquely match exactly one rule — ambiguous matches are rejected. Two-phase: preview → execute with nonce |
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.yamlrealfileandoptionreferences; no filename guessing.realpathboundary 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_TRANSACTIONaborts on concurrent modification.A write returns
COMMITTEDonly 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)
Tool | Description |
| Collect a versioned network baseline and bounded real probes |
| Diagnose DNS structure, exposure, consistency, and reachability |
| Diagnose duplicate, shadowed, invalid, and owner-partitioned rules |
| Diagnose group membership, selections, liveness, and failover |
| Diagnose provider/group health-check intervals, targets, and cost |
| Layered OpenAI connectivity diagnosis without API keys or paid calls |
| Layered GitHub web/API/download diagnosis without repository writes |
| Layered YouTube network diagnosis without account or DRM access |
| Bounded streaming endpoint diagnosis without unlock claims |
| Reject execution when the original baseline has drifted |
| Classify comparable before/after probes as improved, unchanged, regressed, or inconclusive |
| Validate proposed actions against their individual lower-level capability gates |
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)
Tool | Description |
| Read-only inspect of Clash Verge Preferences (Basic/Theme/Layout/Hotkeys) from verge.yaml plus Adapter memory state; sensitive fields (css_injection, WebDAV credentials, system proxy, TUN, DNS, ports) are listed by name only and redacted |
| Write Basic Preferences (language, theme_mode, tray_event, env_type, start_page) with light confirmation. Two-phase preview→confirm; |
| Write Theme Preferences (primary/secondary/text/info/error/warning/success_color, font_family) with light confirmation and ownerFingerprint |
| Write Layout Preferences (traffic_graph, enable_memory_usage, enable_group_icon, pause_render_traffic_stats_on_blur, collapse_navbar, menu_icon, notice_position, enable_hover_jump_navigator, menu_order) with light confirmation and ownerFingerprint |
| Write Hotkeys (enable_global_hotkey + 8 function→accelerator mappings) with strong nonce-bound confirmation. Nonce binds mapping digest + ownerFingerprint + enable state + 60s expiry; one-time use; no replay |
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 positions8 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/hideare native internal shortcuts and are NOT in the allowlistAccelerator 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 Adaptercommon_tray_iconremoved 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
UNVERIFIEDuntil GUI-visible effects are acknowledged;start_pageisPENDING_RESTARTuntil the next Clash Verge launch because closing the dashboard only hides and reuses the current WebView. Hotkeys becomeCOMMITTEDonly when memory,verge.yaml, and the native Tauri registration set all match; incompleteok=truebodies remainUNVERIFIED.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=truefor Basic/Theme/Layout must carry theownerFingerprintreturned 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.yamlbytes (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/HotkeysBodyreject 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_BACKonly when memory, persisted bytes, native side-effect replay, and GUI-refresh scheduling all succeed; missing evidence remainsRECOVERY_REQUIRED.rollbackVerifiednever relies only onpatch_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, neverCOMMITTED.
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 and Platforms
Component | Platform | Verge Rev Version | Status |
Full MCP + Adapter product | macOS Apple Silicon ( | 2.5.1 | supported release path |
Unsigned patch package | macOS Apple Silicon ( | 2.5.1 | required RC asset; not notarized |
Core-only degraded mode | development/recovery only | 2.0.0+ | not an end-user release path |
Any component | any | < 2.0.0 | unsupported |
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_FILEMCP outputs pass through common secret redaction plus tool-specific filtering; runtime Controller/Adapter secrets are also removed if a peer echoes them
No user-controlled arbitrary shell command, filesystem path, URL request, or API endpoint passthrough; all exposed operations use fixed or allowlisted routes, paths, commands, and probe targets
See SECURITY.md for details
FAQ
Where is the Controller secret stored? In the selected MCP client's private
environment configuration. The Adapter token is stored separately in an
owner-only 0600 credentials file and clients receive only its path.
Why are Adapter write tools blocked? The required Adapter installation is missing, incomplete, or no longer verified. Read-only fallback remains available for diagnosis/recovery, but it is not considered a complete release install.
What do PENDING_RESTART and RECOVERY_REQUIRED mean? PENDING_RESTART
requires restarting Clash Verge and the MCP client, then running Adapter
verification. RECOVERY_REQUIRED means automated recovery could not be proven;
stop further writes and follow the recovery section in
ADAPTER-INSTALLATION.md.
How do I remove the Adapter patch? Exit Clash Verge and run
clash-control-adapter patch-uninstall. The uninstaller restores only the
hash-verified official App backup recorded by the installation transaction.
Why does setup reject my existing client config? The installer will not follow symlinks, accept unsafe permissions, or overwrite an entry it cannot prove it owns. Correct the reported permission/ownership issue or configure the MCP entry manually.
Roadmap
See ROADMAP.md.
License
MIT
Available Tools
66 toolsclash.capabilitiesA
Get environment capabilities. MUST be called before any write tools. Returns Mihomo/Verge detection, feature flags, and pending transactions.
Inputs: no named parameters.
clash.config.apply_transactionA
Apply a validated workspace's changes to the persistent config file. Creates a snapshot, writes the file, attempts Mihomo reload, runs health checks, and auto-rolls back on failure. Light confirmation required (confirmed=true).
Inputs: confirmed (required), workspaceId (required).
clash.config.auditA
Audit current configuration for issues with conditional recommendations. Each issue includes: current fact, potential impact, applicability condition.
Inputs: no named parameters.
clash.config.create_workspaceA
Create a config workspace for previewing and validating changes. Reads the merge file (or profile if no merge file exists) and records fingerprints. No files are written. Workspace auto-expires after 5 minutes.
Inputs: no named parameters.
clash.config.get_effectiveA
Get Mihomo runtime effective config (from API /configs). Returns summary by default. Use "section" to get a specific config block (e.g. "dns", "tun").
Inputs: section.
clash.config.get_generatedA
Get Verge generated config (clash-verge.yaml). This is a GENERATED file, NOT a persistent source. Returns summary by default. Use "section" for specific block.
Inputs: section.
clash.config.get_persistentA
Get persistent config sources summary: active profile, merge file, verge settings, and config chain. Does NOT return the generated clash-verge.yaml. Use clash.config.get_generated for that.
Inputs: no named parameters.
clash.config.preview_changeA
Apply semantic changes to a workspace and generate a diff preview. Does NOT write to any file. Supports: set key, merge section (Strategic Merge), rule_add (fingerprint-based), rule_remove (fingerprint-based).
Inputs: changes (required), workspaceId (required).
clash.config.rollbackA
Rollback a previously applied transaction. Restores the original config file from snapshot and attempts to reload Mihomo. Light confirmation required (confirmed=true).
Inputs: confirmed (required), transactionId (required).
clash.config.validate_changeA
Validate a workspace's modified config. Checks YAML syntax, schema, ruleset fingerprint consistency, profile fingerprint consistency, and risk classification. Does NOT write to any file.
Inputs: workspaceId (required).
clash.doctorB
Run comprehensive diagnostics: Mihomo connectivity, Verge detection, privileged service, TUN, system proxy.
Inputs: no named parameters.
clash.merge.inspectA
Inspect a Merge file by uid. Defaults to the active profile's merge reference. Returns DNS/TUN/rules summary, fingerprint, and paginated rules. Read-only.
Inputs: uid, limit, cursor.
clash.merge.updateA
Capability-gated update of a Merge YAML owner with a strategic merge patch through the authenticated native Clash Verge Adapter. targetProfileUid can select an inactive Profile; the owner is resolved from that Profile's option.merge. Two-phase preview/nonce execution with optimistic fingerprint verification and compensation.
Inputs: patch (required), confirmed (required), uid, confirmNonce, +1 more.
clash.optimize.compare_probesA
v1.0-D: Read-only before/after probe comparison. Takes beforeProbes and afterProbes (same targets, same sample counts, same timeouts) and classifies the outcome as IMPROVED, NO_MATERIAL_CHANGE, REGRESSED, or INCONCLUSIVE. Detects critical regression (DNS/HTTP/TCP newly_failing) which requires immediate stop and rollback. Per v1.0-D: config write success alone does NOT constitute optimization success. Does NOT execute probes or modify configuration.
Inputs: afterProbes (required), beforeProbes (required).
clash.optimize.diagnose_networkA
v1.0-A: Read-only network diagnosis. Checks Controller, Adapter, active Profile, run mode, TUN, system proxy, listening ports, DNS, key proxy groups, connections, IPv6 capability, and basic connectivity. Returns a versioned report with facts, probes, findings, recommendations, and proposedActions. Does NOT modify any configuration. Uses predefined safe probe targets only (no arbitrary URL).
Inputs: skipProbes, probeBudgetMs.
clash.optimize.dnsA
v1.0-B: Read-only DNS configuration diagnosis. Checks listen exposure, unreachable servers, IPv4/IPv6 contradiction, invalid fallback, Fake-IP filter, resolution path and timeout. Returns a versioned report with findings and proposedActions. Does NOT modify DNS configuration. DNS strategy recommendations are based on structural evidence only, not regional templates.
Inputs: no named parameters.
clash.optimize.execution_planA
v1.0-D: Read-only execution plan builder. Takes a baselineVerification result and a list of proposedActions, then checks each action against its own independent capability gate (per v1.0-D: no global optimizationWriteEnabled). Returns which actions are executable, which are blocked and why, and the 8-step execution protocol. Does NOT execute any action or modify configuration.
Inputs: proposedActions (required), baselineVerification (required).
clash.optimize.githubA
v1.0-C: Read-only GitHub service network reachability diagnosis. Checks rule coverage for GitHub-related domains, and separately probes web (github.com), API metadata (api.github.com), and download (codeload.github.com) endpoints. Reports failures layer-by-layer (DNS/TCP/TLS/HTTP/rule_match). Does NOT carry GitHub Token, execute push/login/write operations, or read private repo content.
Inputs: skipProbes, probeBudgetMs.
clash.optimize.health_checksA
v1.0-B: Read-only health-check configuration diagnosis. Checks test URL category, interval, timeout, concurrency, lazy mode, and Provider scale. Returns a versioned report with findings and proposedActions. Does NOT modify health-check configuration. Recommendations describe resource cost and timeliness trade-offs.
Inputs: no named parameters.
clash.optimize.openaiA
v1.0-C: Read-only OpenAI service network reachability diagnosis. Checks rule coverage for OpenAI-related domains, API endpoint reachability (without API Key, without calling billing endpoints), and Chat endpoint reachability. Reports failures layer-by-layer (DNS/TCP/TLS/HTTP/rule_match). Does NOT collect API Keys, call billing model endpoints, read chat history, or carry auth credentials. HTTP 401/403 is NOT classified as a network failure.
Inputs: skipProbes, probeBudgetMs.
clash.optimize.proxy_groupsA
v1.0-B: Read-only proxy groups diagnosis. Checks empty groups, invalid references, current selection validity, candidate coverage, strategy type, and failover capability. Returns a versioned report with findings and proposedActions. Does NOT modify proxy groups. Node names are not used to infer real geographic location or quality.
Inputs: no named parameters.
clash.optimize.rulesA
v1.0-B: Read-only rules configuration diagnosis. Checks duplicate rules, invalid proxy references, MATCH position, rule shadowing, and rule count. Returns a versioned report with findings and proposedActions. Does NOT modify rules. Static order analysis cannot prove real traffic hits; runtime verification is required.
Inputs: no named parameters.
clash.optimize.streamingA
v1.0-C: Read-only streaming service network reachability diagnosis. Checks rule coverage for Netflix, Disney+, and Prime Video domains, and probes their web endpoints. Reports failures layer-by-layer (DNS/TCP/TLS/HTTP/rule_match). Does NOT promise unlock, bypass DRM, modify account state, or read watch history. DRM status and region restrictions are NOT classified as network failures.
Inputs: skipProbes, probeBudgetMs.
clash.optimize.verify_baselineA
v1.0-D: Read-only baseline drift verification. Re-collects the current baseline fingerprint and compares it with the original baseline from diagnosis. Returns matched=true if unchanged, or matched=false with drift details if the active Profile, run mode, config chain, proxy group selections, DNS, TUN, system proxy, or ports have changed. Per v1.0-D protocol step 1: if drift is detected, re-diagnose instead of executing proposedActions. Does NOT modify any configuration.
Inputs: originalBaseline (required).
clash.optimize.youtubeA
v1.0-C: Read-only YouTube service network reachability diagnosis. Checks rule coverage for YouTube-related domains (including googlevideo.com, ytimg.com), and probes YouTube web and API endpoints. Reports failures layer-by-layer (DNS/TCP/TLS/HTTP/rule_match). Does NOT promise unlock, modify account state, read watch history, or carry login credentials. HTTP 401/403 is NOT classified as a network failure.
Inputs: skipProbes, probeBudgetMs.
clash.override.inspectA
Inspect the active profile's referenced Script/Override owner, or a specific script UID. The file path is resolved from profiles.yaml; script content is fingerprinted as raw bytes. Read-only.
Inputs: uid.
clash.override.updateA
Capability-gated update of a YAML Override owner through the authenticated native Clash Verge Adapter. JavaScript Script files (.js/.mjs) return NOT_SUPPORTED and are never parsed as YAML or modified by string replacement. Two-phase preview/nonce execution with optimistic fingerprint verification.
Inputs: patch (required), confirmed (required), uid, confirmNonce, +1 more.
clash.profiles.activateA
Activate a Profile through Clash Verge itself. Strong two-step confirmation is required because this may change the active network configuration. First call with confirmed=false to receive a nonce, then retry with confirmed=true and confirmNonce.
Inputs: uid (required), confirmed (required), timeoutMs, confirmNonce.
clash.profiles.inspectB
Inspect a specific Verge profile by uid. Returns config keys and summary.
Inputs: uid (required).
clash.profiles.inspect_chainA
Inspect the active profile's full reference chain: profile, merge, script, rules, proxies, groups layers with per-layer fingerprints. Read-only. Script files are fingerprinted by raw content (not YAML-parsed).
Inputs: no named parameters.
clash.profiles.listC
List Verge profiles with summarized, paginated results.
Inputs: limit, cursor, filter.
clash.profiles.refreshA
Refresh a remote subscription Profile through the authenticated local Clash Verge Adapter. Local profiles return NOT_APPLICABLE. Remote profiles require light confirmation. Capability remains fail-closed and returns BLOCKED when the Adapter is unavailable or unauthenticated. This is a Verge subscription refresh, not a Mihomo Provider refresh.
Inputs: uid (required), confirmed, timeoutMs.
clash.profiles.update_metadataA
Capability-gated update of non-sensitive Profile metadata through the authenticated native Clash Verge Adapter. Allowlist: name, update_interval, desc. Protected fields (uid, type, file, url, option, auth, token, secret) are NEVER modifiable. Two-phase: preview, then confirmed execution with the returned nonce. Fails closed when Adapter evidence is unavailable.
Inputs: uid (required), patch (required), confirmed (required), confirmNonce.
clash.recovery.statusA
Inspect durable transaction and recovery state. Read-only; does not modify manifests, snapshots, profiles, or runtime state.
Inputs: no named parameters.
clash.rules.addA
Capability-gated rule addition to a section (prepend/append/delete) of the independent Rules owner through the authenticated native Clash Verge Adapter. Stable fingerprint anchors are used instead of line numbers; duplicates and drift are rejected. Two-phase preview/nonce execution.
Inputs: rules (required), section (required), confirmed (required), uid, +4 more.
clash.rules.inspectA
Inspect rules from profile, merge, rules layer, or runtime source. Returns ruleset fingerprint, paginated rules with per-rule fingerprints, and MATCH position. Read-only. source="rules" inspects the active profile's independent rules layer (Verge prepend/append/delete enhancement template); use "section" to select which part. For runtime rules use clash.config.get_effective with section="rules".
Inputs: limit, cursor, source, section, +1 more.
clash.rules.removeA
Capability-gated rule removal by unique fingerprint from a section (prepend/append/delete) of the independent Rules owner through the authenticated native Clash Verge Adapter. Ambiguous matches and owner/ruleset drift are rejected. Two-phase preview/nonce execution.
Inputs: section (required), confirmed (required), ruleFingerprints (required), uid, +2 more.
clash.runtime.close_connectionA
Close a specific connection by ID. Does NOT support closing all connections (that requires 强制确认 level). Light confirmation required.
Inputs: confirmed (required), connectionId (required).
clash.runtime.get_proxy_groupA
Read-only: get the safe, paginated candidate names, types, liveness, and recent delay history for one policy group. Does not expose proxy credentials.
Inputs: group (required), limit, cursor, filter.
clash.runtime.get_statusA
Get Mihomo runtime status: version, mode, ports, connections count, traffic totals.
Inputs: no named parameters.
clash.runtime.list_connectionsA
Read-only: list safe, paginated connection summaries including IDs for use with close_connection. IP addresses and local paths are redacted.
Inputs: limit, cursor, filter.
clash.runtime.list_proxy_groupsA
List policy groups with summarized, paginated results.
Inputs: limit, cursor, filter.
clash.runtime.list_proxy_providersA
Read-only: list proxy Provider names and safe runtime summaries for use with refresh_proxy_provider. Subscription URLs and credentials are never returned.
Inputs: limit, cursor, filter.
clash.runtime.list_rule_providersA
Read-only: list rule Provider names and safe runtime summaries for use with refresh_rule_provider. Provider URLs and credentials are never returned.
Inputs: limit, cursor, filter.
clash.runtime.refresh_proxy_providerA
Refresh a proxy provider by name. Per-provider lock prevents concurrent refresh. Light confirmation required. Does NOT modify persistent config.
Inputs: name (required), confirmed (required).
clash.runtime.refresh_rule_providerA
Refresh a rule provider by name. Per-provider lock prevents concurrent refresh. Light confirmation required. Does NOT modify persistent config.
Inputs: name (required), confirmed (required).
clash.runtime.select_proxyA
Switch proxy in a Selector group. With the verified Clash Verge Adapter, atomically synchronizes Mihomo runtime, Verge memory, profiles.yaml, GUI/tray refresh, and optional old-connection cleanup. Otherwise falls back to verified runtime-only switching. Light confirmation required.
Inputs: group (required), proxy (required), confirmed (required).
clash.runtime.test_proxy_delayB
Test delay for a specific proxy with multiple samples. Returns median delay and jitter. Uses predefined test targets only (no arbitrary URL). Auto-allowed.
Inputs: proxy (required), target, samples, timeoutMs.
clash.transaction.resumeB
Resume verification of a persisted PENDING_RESTART transaction after Verge has been restarted. Does not write configuration.
Inputs: transactionId (required).
clash.verge.configure_dns_overrideA
Configure the DNS kernel section in dns_config.yaml (verge_dns_base owner). Strong confirmation required (call first without confirmed to get nonce). DNS resolution verification included.
Inputs: patch (required), confirmed (required), confirmNonce.
clash.verge.configure_lan_accessA
Configure allow-lan in config.yaml (verge_clash_base owner). Strong confirmation required (call first without confirmed to get nonce). LAN binding risk assessment included.
Inputs: value (required), confirmed (required), confirmNonce.
clash.verge.configure_portsA
Configure proxy ports in config.yaml (verge_clash_base owner). Strong confirmation required (call first without confirmed to get nonce). Port listening verification included.
Inputs: value (required), confirmed (required), confirmNonce.
clash.verge.configure_tunA
Configure TUN section in config.yaml (verge_clash_base owner). Strong confirmation required (call first without confirmed to get nonce, then retry with nonce). System-level verification included.
Inputs: patch (required), confirmed (required), confirmNonce.
clash.verge.detectA
Get Clash Verge Rev detection result: version, paths, config root, portable mode, compatibility.
Inputs: no named parameters.
clash.verge.get_active_profileA
Get the currently active Verge profile: uid, type, name, path, selected proxies.
Inputs: no named parameters.
clash.verge.get_directoriesA
Get Verge config directories: config root, profiles dir, executable path, unix socket.
Inputs: no named parameters.
clash.verge.get_settingsA
Read Clash Verge Rev network and runtime settings from verge.yaml.
Inputs: no named parameters.
clash.verge.preferences.configure_hotkeysA
v1.1-C: Modify Clash Verge hotkey mapping. Strong confirmation required (nonce-bound). First call (confirm=false) returns a preview with a nonce; second call (confirm=true with nonce) applies the change. Function names must be in the allowlist (open_or_close_dashboard, clash_mode_rule, clash_mode_global, clash_mode_direct, toggle_system_proxy, toggle_tun_mode, entry_lightweight_mode, reactivate_profiles). Accelerators must match Tauri syntax. System-reserved combos and duplicates are rejected. Requires settings.verge-hotkeys-write capability.
Inputs: mapping (required), enableGlobalHotkey (required), nonce, confirm, +1 more.
clash.verge.preferences.configure_layoutA
v1.1-C: Modify Clash Verge Layout preferences (traffic_graph, enable_memory_usage, enable_group_icon, pause_render_traffic_stats_on_blur, collapse_navbar, menu_icon, notice_position, enable_hover_jump_navigator, menu_order). menu_order must be a non-duplicate subset of real nav paths (/, /proxies, /profile, /connections, /rules, /logs, /unlock, /settings). All fields are IMMEDIATE. Returns a structured Diff in preview mode; call with confirm=true to apply. Requires settings.verge-preferences-write capability.
Inputs: values (required), confirm, ownerFingerprint.
clash.verge.preferences.configure_themeA
v1.1-C: Modify Clash Verge Theme preferences (primary_color, secondary_color, primary_text, secondary_text, info_color, error_color, warning_color, success_color, font_family). Colors must be #RRGGBB or #RRGGBBAA hex strings; pass null for an allowlisted field to restore Verge's unset/default state. font_family rejects URLs, semicolons, braces, and control characters. css_injection and background image paths are NOT opened. Returns a structured Diff in preview mode; call with confirm=true to apply. Requires settings.verge-preferences-write capability.
Inputs: values (required), confirm, ownerFingerprint.
clash.verge.preferences.inspectA
v1.1-A: Read-only inspection of Clash Verge UI preferences (Basic / Theme / Layout / Hotkeys). Returns current values, defaults, schema metadata (risk, confirmation level, effectiveTiming), platform/version support, and validation errors. Reads from Adapter memory state (when authenticated) and verge.yaml. Does NOT require write capability and does NOT trigger GUI refresh, hotkey re-registration, or persistence. Sensitive fields (css_injection, WebDAV credentials, system proxy, TUN, DNS, ports, etc.) are explicitly excluded from the result.
Inputs: no named parameters.
clash.verge.preferences.set_basicA
v1.1-C: Modify Clash Verge Basic UI preferences (language, theme_mode, tray_event, env_type, start_page). Returns a structured Diff in preview mode; call with confirm=true to apply. Requires Adapter authentication and settings.verge-preferences-write capability. All values are validated against real Clash Verge 2.5.1 enums. tray_event is unsupported on Linux. env_type controls copy-env output format (IMMEDIATE, no restart). start_page uses real route paths with leading slash.
Inputs: values (required), confirm, ownerFingerprint.
clash.verge.set_auto_close_connectionA
Enable or disable Clash Verge auto-close connection through the authenticated local Adapter. Updates Verge memory and verge.yaml, emits a GUI refresh, and verifies both states. Light confirmation required.
Inputs: value (required), confirmed (required).
clash.verge.set_ipv6A
Set ipv6 in config.yaml (verge_clash_base owner). Light confirmation required.
Inputs: value (required), confirmed (required).
clash.verge.set_log_levelB
Set log-level in config.yaml (verge_clash_base owner). Light confirmation required.
Inputs: value (required), confirmed (required).
clash.verge.set_unified_delayA
Set unified-delay through the authenticated native Clash Verge Adapter. Light confirmation required; returns COMMITTED only after persistence, runtime, GUI-refresh evidence, and applicable five-state verification succeed.
Inputs: value (required), confirmed (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 66 tools
Each tool has a highly specific purpose within a clear hierarchical namespace (e.g., clash.verge.*, clash.runtime.*). Descriptions are detailed and unique, making it easy to distinguish between similar tools like list vs inspect variants.
All tools follow a consistent pattern: `clash.<category>.<action>`. The hierarchy is uniform, verbs are descriptive (get, set, list, inspect, configure), and snake_case is used throughout without deviations.
At 66 tools, the server is excessively large. While the Clash Verge domain is complex, this many tools in a single server creates cognitive overload and violates typical MCP scoping. The count far exceeds the 15–25 range considered reasonable.
The tool set covers a broad and deep range of operations: profiles, configuration, runtime control, preferences, optimization diagnostics, and recovery. Minor gaps exist (e.g., no direct runtime config write), but core workflows are well-supported.
Maintenance
Related MCP Connectors
Read-only smart-contract security intelligence for autonomous agents.
Read-only finance and operations controls for AI agents with evidence and safe next actions.
Search and read free, scanned AI agent skills and configs. Read-only, no account.
Read-only tools over the Safer Agentic AI framework: 239 patterns + 15 heuristics.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables querying and managing Apache APISIX gateway configurations (routes, services, upstreams, consumers, plugins) through natural language, with read-only mode and write operations requiring confirmation.1540 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to inspect devices and automation rules, preview and apply changes, create backups, compare snapshots, and restore rules on a local MiJia gateway, with writes requiring confirmation.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to control a local Clash Verge Rev / mihomo core on Windows over its named-pipe controller, discovering the live pipe automatically so it works in both sidecar and service mode. Supports inspecting status, switching proxy nodes, latency testing, changing modes, viewing connections and rules, and updating providers.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to control a locally running Bettbox (mihomo-based Clash client) without any client patches, switching proxy nodes, setting routing mode or TUN, testing latency, listing live connections, and adding, removing, or updating subscriptions. All capabilities ride on the client's existing surfaces: the mihomo REST API, its control socket, and its config/profile files.161MIT