Skip to main content
Glama

mihomo-mcp

Bridge mihomo (clash meta) RESTful API to Model Context Protocol. Switch proxies, refresh subscriptions, monitor traffic — directly from your AI client.

License: MIT Python MCP

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-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.

Available Tools

10 tools
connections_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

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Acts 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
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      10
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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