Mihomo MCP Server

基于 MCP (Model Context Protocol) 的 Mihomo/Clash Meta 代理管理服务。
让 AI 助手能自动管理系统代理、工具代理、订阅、规则与内核版本。

---

✨ 功能一览

⚡ Mihomo 管理（12 工具）

工具	说明
mihomo_status	查看 Mihomo 服务状态（版本、API 可达性）
mihomo_start / mihomo_stop	启动/停止 Mihomo 服务
mihomo_version	查看当前版本与更新状态
mihomo_list_versions	列出所有可用版本
mihomo_upgrade	升级/降级到指定版本
mihomo_rollback	回滚到备份版本
list_subscriptions	列出订阅详情（节点数、流量、到期时间）
refresh_subscription	刷新订阅节点列表
add_subscription	添加新订阅（自动重启 Mihomo）
modify_subscription	修改订阅参数
delete_subscription	删除订阅（清理引用 + 本地文件）

🌐 系统代理（11 工具）

工具	说明
list_groups	列出所有代理组及当前节点
list_nodes	列出指定组的节点详情与延迟（并发测试）
switch_node	切换代理组节点
test_delay	测试单个节点延迟
test_connectivity	测试目标网站可达性
batch_test	遍历节点，自动推荐最快节点
list_rules	列出所有路由规则
add_rule	添加路由规则（DOMAIN/IP-CIDR/GEOIP 等）
remove_rule	删除路由规则
add_direct_rule	快捷添加直连规则
add_proxy_rule	快捷添加代理规则

🔧 工具代理（7 工具）

独立 Mihomo 实例（端口 7893），与系统代理完全隔离。

工具	说明
toolproxy_status	查看工具代理运行状态
toolproxy_init	初始化工具代理配置
toolproxy_start / toolproxy_stop	启动/停止工具代理
toolproxy_switch_node	切换工具代理节点
toolproxy_list_nodes	列出工具代理可用节点
run_with_node	在指定节点下执行命令，不影响系统代理，5 分钟空闲自动关闭

---

🚀 快速开始

# 正常启动 MCP 服务器
python3 main.py

# 一键部署（自动安装 Mihomo + 启动 MCP）
python3 main.py --install

# 仅启动 MCP（Mihomo 已就绪时）
python3 main.py --mcp-only

环境要求

• Python ≥ 3.10
• sudo 权限（管理 systemd 服务）
• systemd（Mihomo 服务管理）
• screen（MCP 服务守护）

依赖安装

pip install pyyaml>=6.0

---

🏗 项目结构

mcp_nodes/
├── main.py                  # 入口（3 模式）
├── server.py                # MCP HTTP 服务器（SSE 协议，工具注册）
├── config.py                # 配置常量 + 结构化响应类
├── mihomo_api.py            # Mihomo REST API 封装（含 API Secret 支持）
├── config_manager.py        # YAML 原子读写 + systemctl 管理
├── tools_nodes.py           # 🌐 节点管理工具（并发测试）
├── tools_rules.py           # 📋 规则管理工具
├── tools_subscriptions.py   # 📡 订阅管理工具
├── tools_versions.py        # 🛠 服务控制 + 版本管理
├── tools_toolproxy.py       # 🔧 工具代理（独立 Mihomo 实例，空闲自动停止）
├── install.py               # 📦 一键部署脚本
├── push.py                  # Git 推送脚本（环境变量读取 Token）
├── pyproject.toml           # 项目元数据
├── LICENSE                  # MIT 协议
└── README.md                # 本文档

---

🔌 MCP 协议

服务使用 SSE 协议，绑定 127.0.0.1（仅本地访问）：

SSE 端点: http://127.0.0.1:9010/mcp/sse
消息端点: http://127.0.0.1:9010/mcp/message
健康检查: http://127.0.0.1:9010/health

调用示例

curl -X POST http://127.0.0.1:9010/mcp/message \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_groups", "parameters": {}}'

响应格式

所有工具返回统一结构化响应：

{
  "success": true,
  "data": { ... },
  "message": "操作成功",
  "error": null
}

错误时：

{
  "success": false,
  "data": null,
  "message": "错误描述",
  "error": {
    "code": "ERROR_CODE",
    "details": "详细信息",
    "suggestions": ["建议1", "建议2"]
  }
}

---

⚙ 配置

通过环境变量配置：

变量	默认值	说明
MIHOMO_API	http://127.0.0.1:9090	系统 Mihomo 外部控制器地址
MIHOMO_CONFIG	/etc/mihomo/config.yaml	系统 Mihomo 配置文件路径
GITHUB_TOKEN	""	GitHub API Token（版本管理用）

工具代理端口

端口	说明
7893	工具代理 HTTP/SOCKS5 混合端口
9092	工具代理外部控制器 API

---

🔐 安全说明

• MCP 服务器 绑定 127.0.0.1:9010，仅本地访问
• 工具代理 仅本地端口 7893/9092
• 系统 Mihomo API 自动读取 config.yaml 中的 secret 配置，如果设置了 secret 则所有 API 请求自动带上 Bearer Token
• push.py 从环境变量 GITHUB_TOKEN 读取 Token，不硬编码

---

📦 一键部署（install.py）

python3 install.py              # 完整部署
python3 install.py --dry-run    # 仅检测，不操作
python3 install.py --mcp-only   # 仅启动 MCP

部署流程：

[1/7] 检测 confiug → 检查 Mihomo 安装状态
[2/7] 下载     → GitHub 获取最新内核
[3/7] 安装     → 备份旧版 + 安装新版
[4/7] 配置     → 创建基础 config.yaml
[5/7] 服务     → 创建 systemd 服务
[6/7] 启动     → 启动 + 验证 API
[7/7] MCP      → 启动 MCP 服务器

---

🧪 测试

# 健康检查
curl http://127.0.0.1:9010/health

# 列出代理组
curl -X POST http://127.0.0.1:9010/mcp/message \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_groups", "parameters": {}}'

# 工具代理运行状态
curl -X POST http://127.0.0.1:9010/mcp/message \
  -H "Content-Type: application/json" \
  -d '{"tool": "toolproxy_status", "parameters": {}}'

---

📄 许可证

MIT © 2026 星之游

---

🙏 致谢

• MetaCubeX/mihomo — Mihomo/Clash Meta 内核
• MCP Protocol — Model Context Protocol