surge-mcp-server

DLYZZT/surge-mcp-server

3.2

If you are the rightful owner of surge-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

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

Tools
5
Resources
0
Prompts
0

Surge MCP Server

|

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
  1. Install dependencies:
npm install
  1. 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