DEV Community

Cover image for How to Use Playwright MCP with a Proxy
Nino
Nino

Posted on

How to Use Playwright MCP with a Proxy

Playwright MCP (@playwright/mcp) provides a powerful way for developers to integrate Playwright-driven browser automation into LLM-driven workflows through the Model Context Protocol (MCP). Often, you'll need to use a proxy with your automation tasks—whether to access region-restricted content, secure internal networks, or for debugging purposes. This guide explains clearly how you can configure and run Playwright MCP with a proxy.

🤔 What Exactly is Playwright MCP?

Before diving into the proxy setup, let's briefly discuss what MCP (Model Context Protocol) is:

MCP is an open-source, HTTP-like protocol designed to standardize two-way communication between LLM-powered assistants and external tools like browsers, databases, APIs, CRMs, and messaging services. MCP defines discovery, request/response schemas, and robust security mechanisms to simplify integrations, allowing your AI-driven workflow to perform data fetching or trigger actions without building bespoke integrations from scratch.

Playwright MCP integrates Playwright, a popular browser automation tool, into your MCP-based workflows—unlocking powerful browser automation capabilities directly within your LLM-driven applications.

🔐 Why Use a Proxy with Playwright MCP?

You might want proxy integration for several reasons, such as:

  • Accessing geo-specific content: Proxy servers enable IP-based geo-location changes.
  • Security & Privacy: Proxies can avoid exposing your real IP address.
  • Debugging & testing network scenarios: Simulate certain network constraints or behaviors through proxies.
  • Security compliance: Certain enterprise setups require mandatory proxy usage.
  • Setting up a proxy with Playwright MCP is straightforward—you just specify proxy options within the MCP's built-in configuration.

🛠 Minimal Configuration: Use a Proxy with MCP

Below is a minimal config.json example for configuring MCP to use Playwright with a proxy:

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "proxy": {
        "server": "https://random.instill.network:8080",
        "username": "user",
        "password": "pass"
      },
      "headless": true
    }
  },
  "server": {
    "port": 8931,
    "host": "0.0.0.0"
  }
}
Enter fullscreen mode Exit fullscreen mode

You can add this to your project and run MCP to use Playwright automation with your specified proxy setup.

✅ Advanced Example (Full-Featured Configuration)

Here's a more elaborate example illustrating additional useful settings, like the ability to bypass proxies for certain sites (internal sites) and browser viewport fine-tuning:

proxy-mcp.config.json

{
  "browser": {
    "launchOptions": {
      "proxy": {
        "server": "https://random.instill.network:8080",
        "bypass": "*.internal.example.com",
        "username": "user",
        "password": "pass"
      },
      "headless": true
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  },
  "server": {
    "host": "0.0.0.0",
    "port": 8931
  },
  "capabilities": [ "core", "tabs", "pdf", "wait" ]
}
Enter fullscreen mode Exit fullscreen mode

🏃 Running The MCP Server With Your Proxy Configuration

After creating your configuration file, simply start Playwright MCP:

npx @playwright/mcp@latest --config=proxy-mcp.config.json
Enter fullscreen mode Exit fullscreen mode

The MCP server will now use your defined proxy settings during all Playwright browser automation tasks—super convenient!

🚀 Programmatic Usage (Node.js)

You might want to integrate MCP server proxy configuration directly into your Node.js workflow for custom integrations. Playwright MCP supports this seamlessly:

import http from 'http';
import { createServer } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

(async () => {
  const mcpServer = await createServer({
    browser: {
      launchOptions: {
        proxy: {
          server: 'https://random.instill.network:8080',
          bypass: '*.internal.example.com',
          username: 'user',
          password: 'pass'
        },
        headless: true
      },
      contextOptions: {
        viewport: { width: 1280, height: 720 }
      }
    },
    server: {
      host: '0.0.0.0',
      port: 8931
    },
    capabilities: [ 'core', 'tabs', 'pdf', 'wait' ]
  });

  const server = http.createServer((req, res) => {
    if (req.url === '/messages') {
      const transport = new SSEServerTransport('/messages', res);
      transport.bind(res);
    } else {
      res.writeHead(404);
      res.end();
    }
  });

  server.listen(8931, () => console.log('🚀 MCP server running at http://0.0.0.0:8931'));
})();
Enter fullscreen mode Exit fullscreen mode

🧑‍💻 VSCode Integration Example (Optional)

If you're working directly within Visual Studio Code, you might find it handy to configure MCP integration directly through VSCode settings:

// settings.json snippet
{
  "mcpServers": {
    "playwright": {
      "name": "playwright",
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--config=proxy-mcp.config.json"
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Now, simply run or integrate MCP from within VSCode for convenient browser-fueled workflows.

🌟 Wrapping Up & Next Steps

Configuring Playwright MCP to use a proxy is simple and blends neatly into existing workflows. Utilize the provided examples to streamline your browser automation tasks with ease.

🔥 Ready to Build Powerful AI-Powered Workflows?

Bring your ideas to life and supercharge your AI-driven workflows with Instill AI. Instill provides robust tooling for AI integration, allowing you to seamlessly orchestrate automation tasks, interact with LLM-powered agents, and build next-gen AI infrastructure.

🚀 Explore Instill Network →

Top comments (1)

Collapse
 
trn_phngnguyn_e71b3c profile image
Trần Phương Nguyễn •

Routing LLM browser automation through commercial residential proxies burns cash fast at two dollars per gigabyte. I stopped paying that tax by routing Playwright and MCP instances through FNT vProxy Studio to spin up unlimited local proxy ports using my own free ISP IPv6 subnets and Android USB tethering.