Mobile Proxy for Playwright MCP

Playwright MCP ships two proxy options, documented in the README's configuration table:

Per the README, these arguments "can be provided in the JSON configuration above, as a part of the "args" list" - meaning the same JSON block you already use to register the server in any MCP client. Everything the agent browses then exits through the proxy.

Claude Desktop reads its MCP servers from claude_desktop_config.json. Open it via Settings, then the Developer tab, then Edit Config. On macOS the file lives at ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows at %APPDATA%\Claude\claude_desktop_config.json. Add the flag and its value as two entries in args:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--proxy-server", "http://proxy.mobileproxies.org:8000"
      ]
    }
  }
}

Fully quit and restart Claude Desktop afterwards - the config is only read at launch. The same JSON shape is what the Playwright MCP README calls its "standard config" and it works unchanged in most MCP clients.

Cursor uses the same structure in .cursor/mcp.json (per project) or ~/.cursor/mcp.json (global). This example uses the environment-variable route instead of the flag - every Playwright MCP option has an env var equivalent named PLAYWRIGHT_MCP_*, and MCP clients pass an env object to the server process:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "PLAYWRIGHT_MCP_PROXY_SERVER": "http://proxy.mobileproxies.org:8000"
      }
    }
  }
}

In Claude Code, register the server from the terminal. The -- separator matters: everything after it is passed to the server untouched, so the proxy flag reaches Playwright MCP instead of being parsed by the Claude CLI:

claude mcp add playwright -- npx @playwright/mcp@latest \
  --proxy-server "http://proxy.mobileproxies.org:8000"

SOCKS5 works the same way in any of these: swap the value for socks5://proxy.mobileproxies.org:1080.

Here is the part the README leaves implicit. Its --proxy-server examples are plain scheme://host:port values with no credentials, and embedding user:pass@ in the URL is not a documented pattern. Playwright itself, however, documents a proxy object with server, username, and password fields for authenticated HTTP(S) proxies - and Playwright MCP exposes raw Playwright launch options through its JSON config file. So: put the credentials in a config file and point the server at it.

Save this as playwright-mcp.json somewhere stable (use an absolute path):

{
  "browser": {
    "launchOptions": {
      "proxy": {
        "server": "http://proxy.mobileproxies.org:8000",
        "username": "u_4a9c",
        "password": "p_2X7q"
      }
    }
  }
}

Then reference it from the MCP client config:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--config", "/Users/you/playwright-mcp.json"
      ]
    }
  }
}

The config schema types browser.launchOptions as Playwright's own launch options, which is where the documented proxy object lives. If you would rather keep credentials out of files entirely, IP allowlisting on the proxy side removes the need for a username and password - then the plain --proxy-server flag is all you need.

Do not assume - check. Playwright MCP exposes a browser_get_config tool that returns "the final resolved config after merging CLI options, environment variables and config file," so you can simply ask your agent to call it and confirm the proxy is present. Then have the agent navigate to an IP echo service:

# Prompt for Claude / Cursor once the server is connected:
"Use the Playwright browser to open https://api.ipify.org?format=json
and tell me the IP address shown."

The returned address should be the proxy's exit IP on a mobile carrier ASN, not your own. If it is not, the usual suspects are a client that was not fully restarted after the config edit, a typo in the flag name, or args placed under the wrong server entry.

Two adjacent flags worth knowing: --proxy-bypass excludes domains you want to reach directly (internal dashboards, localhost tooling), and --mobile makes the browser emulate a generic mobile device - a sensible pairing when your egress is a phone network anyway.

Frequently asked questions

Sources

• • microsoft/playwright-mcp README - proxy flags, env vars, standard config, config file schema
• • playwright-mcp issue #58 - maintainer: circumventing bot protection is out of scope
• • Playwright docs - proxy object with server, username, password
• • MCP quickstart - claude_desktop_config.json location, env key, restart requirement
• • Cursor docs - .cursor/mcp.json structure with command, args, env
• • Claude Code docs - claude mcp add syntax and the -- separator