Surge MCP 服务器

English | 简体中文

一个通过 Surge HTTP API 控制 Surge 代理的 Model Context Protocol (MCP) 服务器。

功能特性

此 MCP 服务器通过以下工具类别提供对 Surge 代理的全面控制：

功能开关

• 获取和切换 MITM、抓包、重写和脚本功能

出站模式

• 获取和设置出站模式（直连、代理、规则）

代理策略

• 列出所有可用策略
• 获取策略组详情
• 使用特定 URL 测试策略
• 设置策略组的选中策略

请求管理

• 列出最近和活动的请求
• 终止特定活动请求

配置文件管理

• 获取当前配置文件信息
• 重新加载配置文件

DNS

• 清除 DNS 缓存

模块

• 列出所有可用模块
• 启用/禁用特定模块

脚本

• 列出所有脚本
• 使用模拟环境评估脚本

设备管理（仅限 Mac，需要 Surge 4.0.6+）

• 列出所有活动和已保存的设备
• 修改设备属性（名称、IP 地址、Surge 处理）

前置要求

1. 已安装并运行 Surge
2. 已在 Surge 配置中启用 HTTP API
3. 已安装 Node.js 18+

Surge 配置

在你的 Surge 配置文件中添加以下内容：

[General]
http-api = 你的API密钥@127.0.0.1:6171

将 你的API密钥 替换为你选择的安全 API 密钥。

TLS 支持（可选）：

http-api-tls = true
http-api-web-dashboard = true

安装

1. 克隆此仓库：

git clone <repository-url>
cd surge_mcp

2. 安装依赖：

npm install

3. 构建项目：

npm run build

配置

设置以下环境变量：

export SURGE_HOST=127.0.0.1        # 默认：127.0.0.1
export SURGE_PORT=6171              # 默认：6171
export SURGE_API_KEY=你的API密钥     # 必需：你的 Surge API 密钥

在 Claude Desktop 中使用

在 Claude Desktop 配置文件中添加以下内容：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

方式 1：使用 npx（推荐）

{
  "mcpServers": {
    "surge": {
      "command": "npx",
      "args": ["-y", "surge-mcp-server"],
      "env": {
        "SURGE_HOST": "127.0.0.1",
        "SURGE_PORT": "6171",
        "SURGE_API_KEY": "你的API密钥"
      }
    }
  }
}

方式 2：使用本地安装

{
  "mcpServers": {
    "surge": {
      "command": "node",
      "args": ["/path/to/surge_mcp/dist/index.js"],
      "env": {
        "SURGE_HOST": "127.0.0.1",
        "SURGE_PORT": "6171",
        "SURGE_API_KEY": "你的API密钥"
      }
    }
  }
}

将 /path/to/surge_mcp 替换为此项目的实际路径，将 你的API密钥 替换为你的 Surge API 密钥。

可用工具

功能管理

• surge_get_feature_status - 检查功能状态
• surge_toggle_feature - 启用/禁用功能

出站模式

• surge_get_outbound_mode - 获取当前模式
• surge_set_outbound_mode - 设置模式（直连/代理/规则）

策略管理

• surge_list_policies - 列出所有策略
• surge_get_policy_group - 获取策略组详情
• surge_test_policy - 使用 URL 测试策略
• surge_set_policy_group - 为策略组设置策略

请求管理

• surge_list_requests - 列出最近/活动的请求
• surge_kill_request - 终止活动请求

配置文件管理

• surge_get_profile - 获取当前配置文件
• surge_reload_profile - 重新加载配置文件

DNS

• surge_flush_dns - 清除 DNS 缓存

模块管理

• surge_list_modules - 列出所有模块
• surge_toggle_module - 启用/禁用模块

脚本管理

• surge_list_scripts - 列出所有脚本
• surge_evaluate_script - 使用模拟环境评估脚本

设备管理（仅限 Mac，需要 Surge 4.0.6+）

• surge_list_devices - 列出所有活动和已保存的设备
• surge_modify_device - 修改设备属性

在 Claude 中使用示例

配置完成后，你可以要求 Claude 控制 Surge：

• "Surge 当前的出站模式是什么？"
• "在 Surge 中启用 MITM"
• "列出所有代理策略"
• "将代理组 'Proxy' 设置为使用 'US Server'"
• "显示最近的请求"
• "清除 DNS 缓存"
• "重新加载 Surge 配置文件"
• "列出 Surge 中的所有设备"（仅限 Mac）
• "将 MAC 地址为 XX:XX:XX:XX:XX:XX 的设备重命名为 '我的 iPhone'"（仅限 Mac）

开发

使用自动重建在开发模式下运行：

npm run dev

故障排除

连接问题

• 确保 Surge 正在运行
• 验证 Surge 配置中已启用 HTTP API
• 检查 API 密钥是否匹配
• 确认端口号正确

认证错误

• 仔细检查 API 密钥设置是否正确
• 确保 Surge 配置中的 API 密钥与环境变量匹配

安全说明

• 保护好你的 API 密钥，永远不要将其提交到版本控制系统
• API 密钥授予对 Surge 的完全控制权
• 考虑使用 http-api-tls = true 进行加密通信
• 除非需要远程访问，否则将 API 限制为 localhost（127.0.0.1）

参考

基于官方 Surge HTTP API 文档： https://manual.nssurge.com/others/http-api.html