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: MCP Bridge Server

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:

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

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.