MCP Servers

模型上下文协议服务器、框架、SDK 和模板的综合目录。

M
Mcproxy
作者 @SaladTechnologies
GitHub 仓库(2 星标)

Remote headless browser sessions via MCP (Model Context Protocol) for SaladCloud.

创建于 1/6/2026
更新于 1 day ago
README
View Source
Repository documentation and setup instructions

MCProxy

Remote headless browser sessions via MCP (Model Context Protocol) for SaladCloud.

This project enables AI agents to control browsers running on geographically distributed SaladCloud containers. Use cases include regional price checking, geo-targeted content verification, and web automation from specific locations.

Architecture

┌─────────────────┐     ┌─────────────────────────────────────────────────────┐
│  Agent/Client   │     │              Your Machine                            │
│  (Claude, etc)  │────▶│  ┌───────────────────────────────────────────────┐  │
└─────────────────┘     │  │         MCP Server (stdio)                     │  │
      stdio             │  │  - Manages WebSocket connections               │  │
                        │  │  - 30s heartbeat keepalive                     │  │
                        │  │  - Session ID → connection mapping             │  │
                        │  └──────┬─────────────────────┬──────────────────┘  │
                        └─────────│─────────────────────│──────────────────────┘
                                  │ WSS                 │ WSS
                        ┌─────────▼─────────┐  ┌───────▼───────────┐
                        │  SaladCloud       │  │  SaladCloud       │
                        │  (US Region)      │  │  (EU Region)      │
                        │  ┌─────────────┐  │  │  ┌─────────────┐  │
                        │  │ Browser Srv │  │  │  │ Browser Srv │  │
                        │  │ + Browsers  │  │  │  │ + Browsers  │  │
                        │  └─────────────┘  │  │  └─────────────┘  │
                        └───────────────────┘  └───────────────────┘

Features

  • Multi-Browser Support: Choose between Chromium, Firefox, or WebKit (Safari) for each session
  • Mobile Device Emulation: Emulate 100+ mobile devices (iPhone, Pixel, iPad, Galaxy, etc.) with accurate viewport, user agent, and touch support
  • Location-Aware Sessions: Each session reports its geographic location (IP, city, state/region, country, timezone, ISP). Agents can reference sessions by location (e.g., "use the Utah session")
  • Stealth Mode: Advanced anti-detection with WebGL spoofing, navigator overrides, and realistic browser fingerprints
  • Humanized Interactions: Optional human-like behavior for clicks, typing, and scrolling to avoid bot detection
  • Cloudflare Auto-Wait: Automatically wait for Cloudflare challenges to complete
  • Cookie Persistence: Save and restore cookies for session management and authentication
  • Realistic User Agents: Auto-generates realistic user agents using up-to-date browser fingerprint data
  • Session Affinity: WebSocket connections pin sessions to specific container replicas
  • Heartbeat Keepalive: 30-second pings keep connections alive (Salad gateway has 100s idle timeout)
  • Multi-Region Support: Connect to different Salad deployments for geo-distributed browsing
  • Version Compatibility: Capability reporting with automatic version mismatch detection
  • 33 MCP Tools: Full browser automation including coordinate-based clicking for vision agents

Prerequisites

  • Docker (recommended) or Node.js 20+
  • SaladCloud account (for production deployment)

AI-Assisted Setup

Copy and paste this prompt to your AI agent to help you get mcproxy configured:

Help me set up mcproxy for remote browser automation.

MCP Client: [Claude Desktop / Claude Code / Cursor / Windsurf / other]
SaladCloud Endpoint: [your endpoint URL, or "none" if you need to create one]

Setup steps:
1. Check if I have Docker installed
2. If Docker is available, use the pre-built images from ghcr.io/saladtechnologies/mcproxy
3. If Docker is not available, clone and build from https://github.com/SaladTechnologies/mcproxy
4. Configure the MCP server JSON for my client
5. Generate a secure AUTH_TOKEN
6. Test by creating a browser session

Notes:
- If my endpoint is HTTP/HTTPS, convert it to WSS (wss://...)
- If I don't have an endpoint, guide me to https://portal.salad.com to create a container group
- For local testing without SaladCloud, help me run a local browser server with Docker

Quick Start

1. Install Dependencies

npm install

2. Build

npm run build

3. Local Testing

Start the browser server locally with Docker:

# Start browser server (uses default dev-secret-token)
docker compose up --build

The repo includes a .mcp.json that's pre-configured to work with the Docker Compose setup. To use with Claude Code or other MCP clients that support workspace configs, just run from this directory.

To test manually:

# Uses the same default token as docker-compose
MCPROXY_AUTH_TOKEN=dev-secret-token node mcp-server/dist/index.js

4. Test with MCP Inspector

MCPROXY_AUTH_TOKEN=dev-secret-token npx @modelcontextprotocol/inspector node mcp-server/dist/index.js

Then create a session at ws://localhost:3000.

Using Pre-Built Docker Images

Pre-built Docker images are available on GitHub Container Registry for both components.

Docker Images

| Component | Image | Platforms | |-----------|-------|-----------| | Browser Server | ghcr.io/saladtechnologies/mcproxy/browser-server:latest | linux/amd64 | | MCP Server | ghcr.io/saladtechnologies/mcproxy/mcp-server:latest | linux/amd64, linux/arm64 |

Running Browser Server with Docker

# Start browser server on port 3000
docker run -d \
  --name mcproxy-browser-server \
  -p 3000:3000 \
  -e AUTH_TOKEN=your-secret-token \
  ghcr.io/saladtechnologies/mcproxy/browser-server:latest

Running MCP Server with Docker

The MCP server uses stdio for communication, so it runs interactively with -i flag:

# Run MCP server (connects to local browser server)
docker run --rm -i \
  --network=host \
  -e MCPROXY_AUTH_TOKEN=your-secret-token \
  -e MCPROXY_DEFAULT_ENDPOINT=ws://localhost:3000 \
  ghcr.io/saladtechnologies/mcproxy/mcp-server:latest

MCP Client Configuration with Docker

Configure your MCP client to use the Docker image instead of running from source:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "mcproxy": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "MCPROXY_AUTH_TOKEN=your-secret-token",
        "-e", "MCPROXY_DEFAULT_ENDPOINT=wss://your-salad-endpoint.salad.cloud",
        "ghcr.io/saladtechnologies/mcproxy/mcp-server:latest"
      ]
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "mcproxy": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "MCPROXY_AUTH_TOKEN=your-secret-token",
        "-e", "MCPROXY_DEFAULT_ENDPOINT=wss://your-salad-endpoint.salad.cloud",
        "ghcr.io/saladtechnologies/mcproxy/mcp-server:latest"
      ]
    }
  }
}

Full Local Docker Setup

To test everything locally with Docker (no build required):

# 1. Start browser server
docker run -d \
  --name mcproxy-browser-server \
  -p 3000:3000 \
  -e AUTH_TOKEN=test-token \
  ghcr.io/saladtechnologies/mcproxy/browser-server:latest

# 2. Configure your MCP client to use the MCP server image
#    with MCPROXY_DEFAULT_ENDPOINT=ws://localhost:3000

# 3. When done, clean up
docker stop mcproxy-browser-server && docker rm mcproxy-browser-server

Configuration

Browser Server (Environment Variables)

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | WebSocket server port | | AUTH_TOKEN | (required) | Shared secret for authentication | | MAX_CONTEXTS | 10 | Max browser contexts per container | | CONTEXT_TTL_MS | 1800000 | Context timeout (30 minutes) | | HEALTH_PORT | 8080 | Health/readiness check HTTP port |

Health Check Endpoints

The browser server exposes health check endpoints on HEALTH_PORT (default 8080):

| Endpoint | Description | |----------|-------------| | GET /health | Returns health status with context count. Response: {"status": "healthy", "contexts": 0, "maxContexts": 10} | | GET /ready | Readiness probe. Returns {"ready": true} when server is ready to accept connections |

SaladCloud Configuration:

  • Startup Probe: GET /ready on port 8080 - confirms server is initialized
  • Liveness Probe: GET /health on port 8080 - confirms server is healthy

MCP Server (Environment Variables)

| Variable | Default | Description | |----------|---------|-------------| | MCPROXY_AUTH_TOKEN or AUTH_TOKEN | (required) | Shared secret for authentication | | MCPROXY_HEARTBEAT_INTERVAL_MS | 30000 | Heartbeat interval (30s) | | MCPROXY_COMMAND_TIMEOUT_MS | 30000 | Command timeout (30s) |

MCP Tools

Session Management

| Tool | Description | |------|-------------| | browser_create_session | Create a new browser session with optional browser type and device emulation | | browser_list_sessions | List all active sessions with browser type and location | | browser_close_session | Close a session and free resources | | browser_list_devices | List all available device names for mobile emulation | | browser_get_capabilities | Get server capabilities and check for version mismatches |

browser_create_session Parameters:

  • endpoint (optional): WebSocket endpoint URL (uses MCPROXY_DEFAULT_ENDPOINT if not provided)
  • browser_type (optional): chromium (default), firefox, or webkit (Safari)
  • device (optional): Device to emulate (e.g., "iPhone 15", "Pixel 7", "iPad Pro 11")
  • viewport (optional): { width, height } in pixels (ignored if device is set)
  • userAgent (optional): Custom user agent string (overrides device and random)
  • randomUserAgent (optional): Use a random realistic user agent
  • isMobile (optional): Emulate mobile browser
  • hasTouch (optional): Enable touch events

Navigation

| Tool | Description | |------|-------------| | browser_navigate | Navigate to a URL with optional Cloudflare auto-wait | | browser_go_back | Go back in history | | browser_go_forward | Go forward in history | | browser_reload | Reload the current page |

browser_navigate Parameters:

  • session_id (required): Session ID
  • url (required): URL to navigate to
  • wait_until (optional): load, domcontentloaded, or networkidle
  • wait_for_cloudflare (optional): Auto-wait for Cloudflare challenges to complete
  • cloudflare_timeout (optional): Max wait time in ms (default: 15000)

Interaction (Selector-Based)

| Tool | Description | |------|-------------| | browser_click | Click an element by CSS selector | | browser_type | Type text into an input by selector | | browser_select | Select a dropdown option | | browser_hover | Hover over an element | | browser_scroll | Scroll the page or element |

Interaction (Coordinate-Based)

These tools use relative coordinates (0-1 range) so vision agents can click based on screenshots without worrying about resolution:

  • x=0 is left edge, x=1 is right edge
  • y=0 is top edge, y=1 is bottom edge

| Tool | Description | |------|-------------| | browser_click_at | Click at relative coordinates (0-1 range) | | browser_double_click_at | Double-click at coordinates | | browser_move_mouse | Move mouse to coordinates | | browser_drag | Drag from one position to another |

Example workflow for vision agents:

1. browser_screenshot()           # Get screenshot
2. browser_click_at(0.5, 0.3)    # Click center-top area
3. browser_keyboard_type("hello") # Type at focus
4. browser_keyboard_press("Enter") # Submit

Keyboard (Human-Like Text Entry)

These tools type at the currently focused element (no selector needed), which is more human-like:

| Tool | Description | |------|-------------| | browser_keyboard_type | Type text at current focus | | browser_keyboard_press | Press a key (Enter, Tab, Escape, arrows, or combos like Control+a) | | browser_keyboard_down | Hold down a key (for modifiers) | | browser_keyboard_up | Release a held key |

Humanize Option: Most interaction tools support humanize: true for natural, human-like behavior:

  • Click/Click_at: Natural curved mouse movement to the target
  • Type/Keyboard_type: Random delays between keystrokes (50-150ms)
  • Scroll: Smooth scrolling in small increments with natural timing
  • Move_mouse/Drag: Bezier-curved paths with acceleration/deceleration

Content Extraction

| Tool | Description | |------|-------------| | browser_screenshot | Take a screenshot (returns base64 PNG, can save to file) | | browser_get_content | Get HTML content | | browser_get_text | Get visible text | | browser_evaluate | Execute JavaScript |

Waiting

| Tool | Description | |------|-------------| | browser_wait_for_selector | Wait for an element to appear | | browser_wait_for_navigation | Wait for navigation to complete |

Cookie Management

| Tool | Description | |------|-------------| | browser_get_cookies | Get cookies from the session (optionally filtered by URLs) | | browser_set_cookies | Set cookies in the session (for restoring auth state) | | browser_clear_cookies | Clear all cookies from the session |

Cookie Persistence Example:

# Save cookies after login
cookies = browser_get_cookies(session_id)
# Store cookies somewhere...

# Later, restore session
browser_set_cookies(session_id, cookies)
browser_navigate(session_id, "https://example.com/dashboard")

CAPTCHA Handling

| Tool | Description | |------|-------------| | browser_check_captcha | Check for CAPTCHAs on the page, returns screenshots for agent analysis | | browser_solve_captcha | Submit a CAPTCHA solution after analyzing the image |

CAPTCHA Flow:

  1. browser_navigate automatically detects CAPTCHAs and returns screenshots
  2. Agent analyzes the CAPTCHA image using vision capabilities
  3. Agent calls browser_solve_captcha with the solution
  4. If needed, browser_check_captcha can re-check the page

Supported CAPTCHA types: reCAPTCHA, hCaptcha, Cloudflare Turnstile, FunCaptcha, and generic image/text CAPTCHAs.

MCP Client Configuration

# Clone and build
git clone https://github.com/SaladTechnologies/mcproxy.git
cd mcproxy
npm install
npm run build

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mcproxy": {
      "command": "node",
      "args": ["/path/to/mcproxy/mcp-server/dist/index.js"],
      "env": {
        "MCPROXY_AUTH_TOKEN": "your-secret-token",
        "MCPROXY_DEFAULT_ENDPOINT": "wss://your-salad-endpoint.salad.cloud"
      }
    }
  }
}

Claude Code (VS Code Extension)

Add to your workspace .mcp.json or global settings:

{
  "mcpServers": {
    "mcproxy": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"],
      "env": {
        "MCPROXY_AUTH_TOKEN": "your-secret-token",
        "MCPROXY_DEFAULT_ENDPOINT": "wss://your-salad-endpoint.salad.cloud"
      }
    }
  }
}

Cursor

Add to Cursor's MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mcproxy": {
      "command": "node",
      "args": ["/path/to/mcproxy/mcp-server/dist/index.js"],
      "env": {
        "MCPROXY_AUTH_TOKEN": "your-secret-token",
        "MCPROXY_DEFAULT_ENDPOINT": "wss://your-salad-endpoint.salad.cloud"
      }
    }
  }
}

Windsurf

Add to Windsurf's MCP configuration:

{
  "mcpServers": {
    "mcproxy": {
      "command": "node",
      "args": ["/path/to/mcproxy/mcp-server/dist/index.js"],
      "env": {
        "MCPROXY_AUTH_TOKEN": "your-secret-token",
        "MCPROXY_DEFAULT_ENDPOINT": "wss://your-salad-endpoint.salad.cloud"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can use mcproxy. The server communicates via stdio using the standard MCP protocol. Required environment variables:

  • MCPROXY_AUTH_TOKEN: Authentication token (must match browser server's AUTH_TOKEN)
  • MCPROXY_DEFAULT_ENDPOINT (optional): Default WebSocket endpoint so you don't need to specify it in every browser_create_session call

Deploying to SaladCloud

1. Build and Push Docker Image

# Build the image
docker build -t your-registry/mcproxy-browser:latest -f browser-server/Dockerfile .

# Push to your container registry
docker push your-registry/mcproxy-browser:latest

2. Create Container Group on SaladCloud

  1. Go to SaladCloud Portal
  2. Create a new Container Group
  3. Configure:
    • Image: your-registry/mcproxy-browser:latest
    • Port: 3000
    • Environment Variables:
      • AUTH_TOKEN: Your secret token
      • MAX_CONTEXTS: 10 (adjust based on container resources)
    • Resources: Recommend at least 2GB RAM for browser automation
    • Networking: Enable Container Gateway
    • Startup Probe: HTTP GET /ready on port 8080
    • Liveness Probe: HTTP GET /health on port 8080
  4. Deploy to your desired regions

3. Note Your Endpoints

Each container group will have an endpoint like:

wss://your-org-abc123.salad.cloud

Use these endpoints when creating browser sessions.

Example Usage

Once configured, you can ask Claude to:

Basic Session Creation

Create a browser session at wss://my-salad-endpoint.salad.cloud

Claude will see browser type and location info in the response:

{
  "sessionId": "abc-123",
  "endpoint": "wss://my-salad-endpoint.salad.cloud",
  "browserType": "chromium",
  "location": {
    "ip": "203.0.113.42",
    "city": "Salt Lake City",
    "region": "Utah",
    "regionCode": "UT",
    "country": "United States",
    "countryCode": "US",
    "timezone": "America/Denver",
    "isp": "Example ISP"
  }
}

Mobile Device Emulation

Create an iPhone 15 browser session and navigate to example.com.
Take a screenshot to see the mobile layout.

List available devices that include "iPad" in the name.
Create a session emulating an iPad Pro and check how the site renders.

Humanized Browsing

Create a session and navigate to the login page. Use humanized typing to
enter the username and password, then humanized click to submit the form.
This helps avoid bot detection.

Cloudflare-Protected Sites

Navigate to this Cloudflare-protected site with wait_for_cloudflare enabled.
Wait up to 20 seconds for any challenges to complete automatically.

Multi-Browser Testing

Create a Chromium session and a Firefox session at wss://my-salad-endpoint.salad.cloud.
Navigate both to example.com and take screenshots to compare rendering.

Geo-Distributed Price Comparison

Create 3 browser sessions at wss://my-salad-endpoint.salad.cloud (it will
connect to different replicas). List the sessions and tell me which locations
they're in.

Then use the session in California to check the price of "iPhone 15" on
apple.com, and use the session in Texas to check the same product. Compare
the prices including any tax differences.

Referencing Sessions by Location

List all my browser sessions.

Navigate to netflix.com using the Utah session.

Take a screenshot of the one in New York.

Cookie-Based Session Persistence

Log into the website, then save the cookies. I'll use them later to
restore the session without logging in again.

Security Considerations

  • AUTH_TOKEN: Use a strong, unique token. Rotate periodically.
  • Network Security: The SaladCloud Container Gateway provides the first layer of access control.
  • Session Isolation: Each browser context is isolated. Sessions cannot access each other's data.
  • Sensitive Data: Avoid automating workflows that handle sensitive credentials through browser sessions.

Development

Project Structure

mcproxy/
├── shared/                    # Shared TypeScript types
│   └── src/
│       └── protocol.ts        # WebSocket message types + LocationInfo
├── browser-server/            # Remote browser server
│   └── src/
│       ├── browser-manager.ts # Playwright + stealth
│       ├── location-service.ts# IP geolocation detection
│       ├── ws-server.ts       # WebSocket server
│       ├── command-handler.ts # Command execution
│       └── index.ts           # Entry point
├── mcp-server/                # Local MCP server
│   └── src/
│       ├── browser-client.ts  # WebSocket client
│       ├── session-manager.ts # Session management + location tracking
│       ├── tools/             # MCP tool definitions
│       └── index.ts           # Entry point
├── docker-compose.yml         # Local development
└── package.json               # Monorepo configuration

Building

# Build all packages
npm run build

# Build specific package
npm run build:shared
npm run build:browser-server
npm run build:mcp-server

Running in Development

# Browser server (with hot reload)
npm run dev:browser-server

# MCP server (with hot reload)
npm run dev:mcp-server

Troubleshooting

Connection Timeouts

If sessions disconnect unexpectedly:

  • Check that heartbeat interval (30s default) is less than Salad's idle timeout (100s)
  • Verify network connectivity to the SaladCloud endpoint
  • Check container logs for errors

Bot Detection

If sites detect automation:

  • The stealth plugin handles most cases automatically
  • Use humanize: true on click, type, and scroll actions for human-like behavior
  • Try randomUserAgent: true when creating sessions to rotate fingerprints
  • Use mobile device emulation (device: "iPhone 15") - mobile browsers are often trusted more
  • For Cloudflare-protected sites, use wait_for_cloudflare: true on navigate

Cloudflare Challenges

If Cloudflare challenges aren't completing:

  • Increase cloudflare_timeout (default is 15 seconds)
  • Some challenges require interaction - check for interactive CAPTCHAs
  • Try a different browser type (Firefox or WebKit)
  • Use browser_check_captcha to see what type of challenge is present

Version Mismatches

If you see unexpected behavior or missing features:

  • Use browser_get_capabilities to check server version and supported features
  • The tool will warn if browser server and MCP server versions are mismatched
  • Update the component that's behind (recommendation provided in response)

Navigation Errors with networkidle

If navigation fails with net::ERR_ABORTED when using wait_until: networkidle:

  • Sites with dynamic content or continuous network activity may never reach "network idle"
  • Use load or domcontentloaded instead (default is domcontentloaded)
  • networkidle is best for static pages or when you need all resources fully loaded
  • For most use cases, the default domcontentloaded is fastest and most reliable

Screenshots and File Handling

Screenshots from browser_screenshot are returned as base64 and displayed inline in MCP responses:

  • The inline image display works automatically - no need to use present_files or similar tools
  • The optional file_path parameter saves to disk as a convenience but the base64 response is the primary output
  • If using file_path, the file is saved on the machine running the MCP server (your local machine), not the remote browser server

Memory Issues

If the browser server runs out of memory:

  • Increase container memory allocation on SaladCloud (recommend 4GB+ for heavy automation)
  • Reduce MAX_CONTEXTS to limit concurrent browser contexts
  • Close sessions when done with browser_close_session
  • Use browser_clear_cookies between different site visits in the same session

License

MIT

快速设置
此服务器的安装指南

安装包 （如果需要）

npx @modelcontextprotocol/server-mcproxy

Cursor 配置 (mcp.json)

{ "mcpServers": { "saladtechnologies-mcproxy": { "command": "npx", "args": [ "saladtechnologies-mcproxy" ] } } }