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

Requirements

• Python 3.10+
• mihomo running with external-controller enabled
• An 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: 10

Environment variables override file values:

Var	Default
MIHOMO_HOST	127.0.0.1
MIHOMO_PORT	9090
MIHOMO_SECRET	(empty)
MIHOMO_TIMEOUT	10

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
proxy_list	List all proxy groups and their current selection
proxy_select	Switch a selector group to a specific proxy
proxy_test	Test latency of a single proxy
proxy_test_group	Test all proxies in a group, sorted by latency
provider_list	List providers (subscriptions) and node counts
provider_healthcheck	Trigger health check on a provider
provider_update_url	Update provider's subscription URL and refresh
mode_set	Switch operating mode (rule / global / direct)
connections_list	List active connections

Security & Privacy

1. No subscription URL is persisted. The provider_update_url tool receives a URL via MCP, forwards it to mihomo, and discards it. Nothing is logged or written to disk.
2. Default host is 127.0.0.1. Overriding host to a public IP is not recommended and may be rejected in future versions.
3. No credentials stored. If your mihomo has external-controller-secret, pass it via MIHOMO_SECRET env var — never in config files checked into version control.
4. No traffic proxying. This package only manages mihomo state — it does not forward your traffic.
5. 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.