Content
# Mihomo MCP Server
> A Mihomo/Clash Meta proxy management service based on MCP (Model Context Protocol).
> Enables AI assistants to automatically manage system proxies, tool proxies, subscriptions, rules, and kernel versions.
[](LICENSE)
---
## ✨ Feature List
### ⚡ Mihomo Management (12 tools)
| Tool | Description |
|:----|:-----|
| `mihomo_status` | Check Mihomo service status (version, API accessibility) |
| `mihomo_start` / `mihomo_stop` | Start/stop Mihomo service |
| `mihomo_version` | Check current version and update status |
| `mihomo_list_versions` | List all available versions |
| `mihomo_upgrade` | Upgrade/downgrade to a specified version |
| `mihomo_rollback` | Roll back to the backup version |
| `list_subscriptions` | List subscription details (node count, traffic, expiration time) |
| `refresh_subscription` | Refresh subscription node list |
| `add_subscription` | Add a new subscription (automatically restart Mihomo) |
| `modify_subscription` | Modify subscription parameters |
| `delete_subscription` | Delete a subscription (clean up references and local files) |
### 🌐 System Proxy (11 tools)
| Tool | Description |
|:----|:-----|
| `list_groups` | List all proxy groups and current nodes |
| `list_nodes` | List node details and latency for a specified group (concurrent testing) |
| `switch_node` | Switch proxy group nodes |
| `test_delay` | Test single node latency |
| `test_connectivity` | Test target website accessibility |
| `batch_test` | Traverse nodes, automatically recommend the fastest node |
| `list_rules` | List all routing rules |
| `add_rule` | Add routing rules (DOMAIN/IP-CIDR/GEOIP, etc.) |
| `remove_rule` | Delete routing rules |
| `add_direct_rule` | Quickly add direct connection rules |
| `add_proxy_rule` | Quickly add proxy rules |
### 🔧 Tool Proxy (7 tools)
Independent Mihomo instance (port 7893), completely isolated from system proxy.
| Tool | Description |
|:----|:-----|
| `toolproxy_status` | Check tool proxy running status |
| `toolproxy_init` | Initialize tool proxy configuration |
| `toolproxy_start` / `toolproxy_stop` | Start/stop tool proxy |
| `toolproxy_switch_node` | Switch tool proxy nodes |
| `toolproxy_list_nodes` | List available tool proxy nodes |
| `run_with_node` | **Execute commands under a specified node, without affecting system proxy, automatically close after 5 minutes of idle** |
---
## 🚀 Quick Start
```bash
# Normally start MCP server
python3 main.py
# One-click deployment (automatically install Mihomo + start MCP)
python3 main.py --install
# Start MCP only (when Mihomo is ready)
python3 main.py --mcp-only
```
### Requirements
- **Python** ≥ 3.10
- **sudo privileges** (manage systemd services)
- **systemd** (Mihomo service management)
- **screen** (MCP service daemon)
### Dependency Installation
```bash
pip install pyyaml>=6.0
```
---
## 🏗 Project Structure
```
mcp_nodes/
├── main.py # Entry (3 modes)
├── server.py # MCP HTTP server (SSE protocol, tool registration)
├── config.py # Configuration constants + structured response classes
├── mihomo_api.py # Mihomo REST API encapsulation (with API Secret support)
├── config_manager.py # YAML atomic read/write + systemctl management
├── tools_nodes.py # 🌐 Node management tools (concurrent testing)
├── tools_rules.py # 📋 Rule management tools
├── tools_subscriptions.py # 📡 Subscription management tools
├── tools_versions.py # 🛠 Service control + version management
├── tools_toolproxy.py # 🔧 Tool proxy (independent Mihomo instance, automatically stop when idle)
├── install.py # 📦 One-click deployment script
├── push.py # Git push script (environment variable reads Token)
├── pyproject.toml # Project metadata
├── LICENSE # MIT license
└── README.md # This document
```
---
## 🔌 MCP Protocol
Service uses **SSE** protocol, bound to `127.0.0.1` (local access only):
```
SSE endpoint: http://127.0.0.1:9010/mcp/sse
Message endpoint: http://127.0.0.1:9010/mcp/message
Health check: http://127.0.0.1:9010/health
```
### Example Call
```bash
curl -X POST http://127.0.0.1:9010/mcp/message \
-H "Content-Type: application/json" \
-d '{"tool": "list_groups", "parameters": {}}'
```
### Response Format
All tools return a unified structured response:
```json
{
"success": true,
"data": { ... },
"message": "Operation successful",
"error": null
}
```
Error:
```json
{
"success": false,
"data": null,
"message": "Error description",
"error": {
"code": "ERROR_CODE",
"details": "Detailed information",
"suggestions": ["Suggestion 1", "Suggestion 2"]
}
}
```
---
## ⚙ Configuration
Configured through environment variables:
| Variable | Default value | Description |
|:----|:------|:-----|
| `MIHOMO_API` | `http://127.0.0.1:9090` | System Mihomo external controller address |
| `MIHOMO_CONFIG` | `/etc/mihomo/config.yaml` | System Mihomo configuration file path |
| `GITHUB_TOKEN` | `""` | GitHub API Token (for version management) |
### Tool Proxy Port
| Port | Description |
|:----:|:------|
| 7893 | Tool proxy HTTP/SOCKS5 mixed port |
| 9092 | Tool proxy external controller API |
---
## 🔐 Security Instructions
- **MCP server** bound to `127.0.0.1:9010`, local access only
- **Tool proxy** only on local port 7893/9092
- **System Mihomo API** automatically reads the `secret` configuration in `config.yaml`, if a secret is set, all API requests automatically carry a Bearer Token
- **push.py** reads Token from environment variable `GITHUB_TOKEN`, no hard coding
---
## 📦 One-Click Deployment (`install.py`)
```bash
python3 install.py # Complete deployment
python3 install.py --dry-run # Only detect, no operation
python3 install.py --mcp-only # Start MCP only
```
Deployment process:
```
[1/7] Detect config → Check Mihomo installation status
[2/7] Download → Get the latest kernel from GitHub
[3/7] Install → Backup old version + install new version
[4/7] Configure → Create basic config.yaml
[5/7] Service → Create systemd service
[6/7] Start → Start + verify API
[7/7] MCP → Start MCP server
```
---
## 🧪 Testing
```bash
# Health check
curl http://127.0.0.1:9010/health
# List proxy groups
curl -X POST http://127.0.0.1:9010/mcp/message \
-H "Content-Type: application/json" \
-d '{"tool": "list_groups", "parameters": {}}'
# Tool proxy running status
curl -X POST http://127.0.0.1:9010/mcp/message \
-H "Content-Type: application/json" \
-d '{"tool": "toolproxy_status", "parameters": {}}'
```
---
## 📄 License
[MIT](LICENSE) © 2026 Star Tour
---
## 🙏 Acknowledgements
- [MetaCubeX/mihomo](https://github.com/MetaCubeX/mihomo) — Mihomo/Clash Meta kernel
- [MCP Protocol](https://modelcontextprotocol.io/) — Model Context Protocol
