mihomo-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., "@mihomo-mcp Test all proxies in the group and switch to the fastest"
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.
mihomo-mcp
Bridge mihomo (clash meta) RESTful API to Model Context Protocol. Switch proxies, refresh subscriptions, monitor traffic — directly from your AI client.
Status: v0.1.0 (public) — 9 tools, 17 tests, verified on mihomo v1.19.24
What is mihomo-mcp?
mihomo exposes a powerful RESTful API on 127.0.0.1:9090 (external-controller). This package wraps that API as MCP tools, so an AI client (Claude Code, OpenClaw, Cursor, etc.) can:
List and switch proxy groups
Test proxy latency
Refresh provider subscriptions
Update provider subscription URL (without restart in many cases)
Set operating mode (rule / global / direct)
Inspect active connections
Related MCP server: Mihomo MCP Server
Requirements
Python 3.10+
mihomo running with
external-controllerenabledAn MCP-compatible client (OpenClaw, Claude Code, Claude Desktop, etc.)
Not affiliated with mihomo. This is a community project.
Installation
# Recommended (uv)
uv tool install mihomo-mcp
# Or pip
pip install mihomo-mcp
# Or from source
git clone https://github.com/Aris-qin/mihomo-mcp.git
cd mihomo-mcp
pip install -e .Configuration
# ~/.config/mihomo-mcp/config.yaml
mihomo:
host: 127.0.0.1
port: 9090
secret: "" # if mihomo has external-controller-secret
timeout: 10Environment variables override file values:
Var | Default |
|
|
|
|
| (empty) |
|
|
Register with OpenClaw
In openclaw.json:
{
"mcp": {
"servers": {
"mihomo": {
"type": "stdio",
"command": "mihomo-mcp",
"env": {
"MIHOMO_HOST": "127.0.0.1",
"MIHOMO_PORT": "9090"
}
}
}
}
}Register with Claude Desktop
Edit claude_desktop_config.json:
{
"mcpServers": {
"mihomo": {
"command": "mihomo-mcp",
"env": {
"MIHOMO_HOST": "127.0.0.1",
"MIHOMO_PORT": "9090"
}
}
}
}Tools
Tool | Description |
| List all proxy groups and their current selection |
| Switch a selector group to a specific proxy |
| Test latency of a single proxy |
| Test all proxies in a group, sorted by latency |
| List providers (subscriptions) and node counts |
| Trigger health check on a provider |
| Update provider's subscription URL and refresh |
| Switch operating mode (rule / global / direct) |
| List active connections |
Security & Privacy
No subscription URL is persisted. The
provider_update_urltool receives a URL via MCP, forwards it to mihomo, and discards it. Nothing is logged or written to disk.Default host is
127.0.0.1. Overriding host to a public IP is not recommended and may be rejected in future versions.No credentials stored. If your mihomo has
external-controller-secret, pass it viaMIHOMO_SECRETenv var — never in config files checked into version control.No traffic proxying. This package only manages mihomo state — it does not forward your traffic.
Not affiliated with mihomo. Community project, MIT licensed.
License
MIT — see LICENSE.
Contributing
PRs welcome after the initial public release. Please open an issue first for major changes.
Available Tools
10 toolsconnections_listA
List active connections (source ip, host, rule, chains, upload, download).
Returns a list of connection objects. An empty list means no active connections (mihomo returns {connections: null} on idle).
Inputs: no named parameters.
mode_setA
Switch operating mode: rule (default), global, or direct.
Args: mode: one of "rule", "global", "direct"
rule: use rules to decide what goes through proxy
global: all traffic through proxy
direct: all traffic bypasses proxy
Inputs: mode (required).
provider_healthcheckA
Trigger health check on a provider (force-refresh + delay measurement).
Args: provider: provider name (e.g. "MyVPN")
Returns a no-content confirmation (mihomo returns 204). The actual health state is observable via provider_list.
Inputs: provider (required).
provider_listA
List all proxy providers with node counts and last update info.
Returns: list of {name, type, vehicle_type, node_count, updated_at}.
Inputs: no named parameters.
provider_update_urlA
Update a provider's subscription URL and trigger a refresh.
Args: provider: provider name url: new subscription URL (forwarded to mihomo, never persisted)
The URL is sent to mihomo via PUT and used immediately. It is not cached, logged, or written to disk by this server.
Inputs: url (required), provider (required).
proxy_listA
List all proxy groups with their current selection and node count.
Returns a list of groups, each with: name, type, current (the active proxy), and the number of available nodes. Selector/URLTest groups show all options; Direct/Reject/Compatible show a single fixed value.
Inputs: no named parameters.
proxy_selectA
Switch a Selector/URLTest group to a specific proxy.
Args: group: the group name (e.g. "GLOBAL", "Manual") proxy: the proxy name to select (e.g. "🇭🇰香港01 [1×] - Lv.4")
Returns the new selection. Mihomo returns 400 if the proxy is not in the group's all-list (case-sensitive).
Inputs: group (required), proxy (required).
proxy_testA
Test latency (ms) for a single proxy.
Args: proxy: proxy name (must match an entry in a group's all-list) url: target URL, default is gstatic.com/generate_204 (used by mihomo itself) timeout_ms: per-test timeout in milliseconds (default 5000)
Returns the delay in ms, or {"delay": -1} if the test failed.
Inputs: proxy (required), url, timeout_ms.
proxy_test_groupA
Test latency of every proxy in a group, sorted by delay (fastest first).
Args: group: the selector group to test url: target URL timeout_ms: per-proxy timeout concurrency: max parallel probes (default 8)
Returns a list of {name, delay_ms, ok} sorted by delay. Failed probes show delay=-1 and are placed at the end.
Inputs: group (required), url, timeout_ms, concurrency.
versionA
Return mihomo-mcp package version and connected mihomo version.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct resource+action: proxy_test vs proxy_test_group are clearly separate (single proxy vs group), provider_list/healthcheck/update_url each cover a unique provider operation, and mode_set, connections_list, and version are unambiguous. No two tools could be easily confused.
Names are mostly snake_case with a resource prefix and a verb (proxy_list, proxy_select, provider_update_url, mode_set), but 'version' is a bare noun and 'provider_healthcheck' is a compound rather than a clear verb_noun pattern. The slight inconsistencies are minor and do not harm readability.
10 tools is within the well-scoped 3-15 range. Each tool serves a meaningful operational purpose for controlling a mihomo proxy client, with no redundancy or bloat.
Core proxy operations are covered: list proxies, select proxy, test single/group latency, manage providers, set mode, view connections, and version. Missing features like config read/write or connection termination are minor gaps that do not block primary workflows.
Maintenance
Related MCP Connectors
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
A Model Context Protocol server for Wix AI tools
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceActs as a bridge between standard REST/OpenAPI web APIs and the Model Context Protocol, dynamically converting REST endpoints into MCP tools for LLM clients like Cursor, Claude Desktop, and n8n.Apache 2.0
- AlicenseNot gradedqualityDmaintenance基于MCP协议的Mihomo/Clash Meta代理节点管理服务,允许AI助手自动管理代理节点、订阅、服务控制和内核版本。2MIT
- AlicenseAqualityCmaintenanceEnables AI/MCP clients to manage a local mihomo/Clash Meta core by switching proxies, testing latency, viewing or closing connections, changing modes, and toggling TUN and Windows system proxy settings through a named pipe or HTTP control channel.10MIT
- 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