AI导哈

Surge代理控制服务器

一个通过HTTP API全面控制Surge代理功能的MCP服务器，提供策略管理、请求控制、配置文件操作等功能。

  • by DLYZZT
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 DLYZZT/surge-mcp-server

使用说明

MCP服务器激增

英语 | 简体中文

一个用于通过其HTTP API控制Surge代理的模型上下文协议（MCP）服务器。

特点

这款MCP服务器通过以下工具类别，为Surge代理提供全面的控制功能：

功能切换

  • 获取并切换MITM（中间人攻击）、捕获、重写和脚本功能

外向模式

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

代理策略

  • 列出所有可用的策略
  • 获取策略组详细信息
  • 使用特定URL测试策略
  • 为策略组设置选定策略

请求管理

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

配置文件管理

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

DNS（域名系统）

  • 刷新DNS缓存

模块

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

脚本编写

  • 列出所有脚本
  • 在模拟环境中评估脚本

设备管理（仅限Mac，Surge 4.0.6及以上版本）

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

先决条件

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

涌浪配置

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

[General]
http-api = YOUR_API_KEY@127.0.0.1:6171

替换 YOUR_API_KEY 使用您选择的安全API密钥。

对于TLS支持（可选）：

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

安装

  1. 克隆此存储库：
git clone https://github.com/DLYZZT/surge-mcp-server.git
cd surge_mcp
  1. 安装依赖项：
npm install
  1. 构建项目：
npm run build

配置

设置以下环境变量：

export SURGE_HOST=127.0.0.1        # Default: 127.0.0.1
export SURGE_PORT=6171              # Default: 6171
export SURGE_API_KEY=YOUR_API_KEY   # Required: Your Surge API key

与Claude Desktop的配合使用

在您的Claude桌面配置文件中添加以下内容：

macOS（发音为“Mac OS”，全称为“Macintosh Operating System”，中文常译为“苹果电脑操作系统”或简称为“苹果系统”）： ~/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": "YOUR_API_KEY"
      }
    }
  }
}

选项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": "YOUR_API_KEY"
      }
    }
  }
}

替换 /path/to/surge_mcp 以及这个项目的实际路径 YOUR_API_KEY 使用您的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（Domain Name System，域名系统）

  • 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”设置为使用“美国服务器”
  • “显示最近的请求”
  • “刷新DNS缓存”
  • “重新加载突增配置文件”
  • “列出 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限制为本地主机（127.0.0.1（除非需要远程访问）

参考

根据官方Surge HTTP API文档： https://manual.nssurge.com/others/http-api.html 翻译成中文为：“https://manual.nssurge.com/others/http-api.html（NSSurge 手册 - 其他 - HTTP API 页面）”。不过，通常网址本身在中文语境下不会直接翻译，而是保持原样，因为网址是国际通用的。所以，如果仅从翻译的角度来看，可以理解为“NSSurge 手册中的 HTTP API 部分”，但实际使用时仍会保留原网址形式

相关 MCP