# Surge MCP Server

[English](README.md) | [简体中文](README.zh-CN.md)

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:

```ini
[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):

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

## Installation

1. Clone this repository:
```bash
git clone https://github.com/DLYZZT/surge-mcp-server.git
cd surge_mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Configuration

Set the following environment variables:

```bash
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)

```json
{
  "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

```json
{
  "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:

```bash
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