MCProxy

You can run remote, geo-aware browser sessions through MCP to automate tasks, verify content, and compare results across regions. This MCP server coordinates browser instances on distributed SaladCloud containers and lets AI agents drive those browsers securely and efficiently.

How to use

Create and manage browser sessions from an MCP client to run automated browsing tasks. Choose the browser type (Chromium, Firefox, or WebKit), emulate devices like iPhone or Pixel, and assign sessions to specific locations to mirror regional access. Use the built-in stealth features, Cloudflare auto-wait, and human-like interaction options to reduce detection while performing tasks such as price checks, content verification, or automated testing.

How to install

Prerequisites are Docker (recommended) or Node.js 20+, plus a SaladCloud account if you are deploying to production.

npm install

npm run build

Additional setup tips

For local testing, you can run a browser server and an MCP server in tandem with Docker. Use the default development token for testing and then switch to a secure token for production.

# Start browser server on port 3000
docker compose up --build

# Test locally with MCP server
MCPROXY_AUTH_TOKEN=dev-secret-token node mcp-server/dist/index.js

Configuration

Configure the browser server and the MCP server using environment variables. The browser server exposes health and readiness endpoints to support container orchestration. The MCP server handles client connections, heartbeats, and session mappings.

Security

Use a strong, unique AUTH_TOKEN for the browser and MCP servers. Enable container gateway access control and rotate credentials regularly. Each browser context remains isolated to protect data between sessions.

Troubleshooting

If sessions disconnect or Cloudflare challenges appear, adjust the wait and timeout settings, enable Cloudflare auto-wait, or apply human-like interaction options to reduce bot-detection signals.

Deploying to SaladCloud

Follow these steps to deploy to SaladCloud using pre-built images and container groups. This approach provides scalable, geo-distributed browser sessions.

Example usage

Create a browser session at a SaladCloud endpoint, emulate a device like iPhone 15, navigate to a site, and take a screenshot for verification. You can run multiple sessions across regions to compare results.

Available tools

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_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_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

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

browser_keyboard_type

Type text at current focus with human-like timing

browser_keyboard_press

Press a key or key combination

browser_keyboard_down

Hold down a key for modifiers

browser_keyboard_up

Release a held key

browser_screenshot

Take a screenshot and return base64 data

browser_get_content

Get HTML content of the page or region

browser_get_text

Get visible text from the page

browser_evaluate

Execute JavaScript in the page context

browser_wait_for_selector

Wait for an element to appear

browser_wait_for_navigation

Wait for navigation to complete

browser_get_cookies

Get cookies from the session

browser_set_cookies

Set cookies in the session

browser_clear_cookies

Clear all cookies from the session

browser_check_captcha

Check for CAPTCHAs on the page and return analysis data

browser_solve_captcha

Submit a CAPTCHA solution after analysis