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"
  }
}

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" ]
}

🏃 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

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'));
})();

🧑‍💻 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"
      ]
    }
  }
}

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 →