Surge MCP Server

English | 简体中文

A Model Context Protocol (MCP) server for controlling Surge proxy via its HTTP API.

Features

This MCP server provides comprehensive control over Surge proxy through the following tool categories:

Features Toggle

• Get and toggle MITM, Capture, Rewrite, and Scripting features

Outbound Mode

• Get and set outbound mode (direct, proxy, rule)

Proxy Policies

• List all available policies
• Get policy group details
• Test policies with specific URLs
• Set selected policy for policy groups

Request Management

• List recent and active requests
• Kill specific active requests

Profile Management

• Get current profile information
• Reload profile

DNS

• Flush DNS cache

Modules

• List all available modules
• Enable/disable specific modules

Scripting

• List all scripts
• Evaluate scripts with mock environment

Device Management (Mac Only, Surge 4.0.6+)

• List all active and saved devices
• Modify device properties (name, IP address, Surge handling)

Prerequisites

1. Surge installed and running
2. HTTP API enabled in Surge configuration
3. Node.js 18+ installed

Surge Configuration

Add the following to your Surge configuration file:

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

Replace YOUR_API_KEY with a secure API key of your choice.

For TLS support (optional):

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

Installation

1. Clone this repository:

git clone https://github.com/DLYZZT/surge-mcp-server.git
cd surge_mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Set the following environment variables:

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

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Using npx (Recommended)

{
  "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"
      }
    }
  }
}

Option 2: Using local installation

{
  "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"
      }
    }
  }
}

Replace /path/to/surge_mcp with the actual path to this project and YOUR_API_KEY with your Surge API key.

Available Tools

Feature Management

• surge_get_feature_status - Check status of features
• surge_toggle_feature - Enable/disable features

Outbound Mode

• surge_get_outbound_mode - Get current mode
• surge_set_outbound_mode - Set mode (direct/proxy/rule)

Policy Management

• surge_list_policies - List all policies
• surge_get_policy_group - Get policy group details
• surge_test_policy - Test policies with URL
• surge_set_policy_group - Set policy for group

Request Management

• surge_list_requests - List recent/active requests
• surge_kill_request - Kill active request

Profile Management

• surge_get_profile - Get current profile
• surge_reload_profile - Reload profile

DNS

• surge_flush_dns - Flush DNS cache

Module Management

• surge_list_modules - List all modules
• surge_toggle_module - Enable/disable module

Script Management

• surge_list_scripts - List all scripts
• surge_evaluate_script - Evaluate script with mock environment

Device Management (Mac Only, Surge 4.0.6+)

• surge_list_devices - List all active and saved devices
• surge_modify_device - Modify device properties

Example Usage in Claude

Once configured, you can ask Claude to control Surge:

• "What's the current outbound mode in Surge?"
• "Enable MITM in Surge"
• "List all proxy policies"
• "Set the proxy group 'Proxy' to use 'US Server'"
• "Show me recent requests"
• "Flush DNS cache"
• "Reload Surge profile"
• "List all devices in Surge" (Mac only)
• "Rename the device with MAC address XX:XX:XX:XX:XX:XX to 'My iPhone'" (Mac only)

Development

Run in development mode with auto-rebuild:

npm run dev

Troubleshooting

Connection Issues

• Ensure Surge is running
• Verify HTTP API is enabled in Surge configuration
• Check that the API key matches
• Confirm the port number is correct

Authentication Errors

• Double-check your API key is set correctly
• Ensure the API key in Surge config matches the environment variable

Security Notes

• Keep your API key secure and never commit it to version control
• The API key grants full control over Surge
• Consider using http-api-tls = true for encrypted communication
• Restrict the API to localhost (127.0.0.1) unless remote access is needed

Reference

Based on the official Surge HTTP API documentation: https://manual.nssurge.com/others/http-api.html