Integration with MCP

This guide explains how to integrate Oxylabs Unblocking Browser with MCP (Model Context Protocol) to enable AI systems to interact with and control remote browsers.

Visit the Oxylabs GitHub repository for a complete working example of MCP integration with the Oxylabs Unblocking Browser.

Overview

Model Control Protocol (MCP) allows AI systems like Claude to interact with browsers and perform web-based tasks. By integrating Oxylabs Unblocking Browser with MCP, you can leverage AI systems to perform web navigation, data retrieval, and automation tasks using remote browsers with advanced stealth capabilities and Residential Proxy integration.

The MCP host (such as Claude Desktop or Cursor) comes with a built-in MCP client. Playwright-MCP acts as an MCP server, and instead of using a local browser, it connects to Unblocking Browser via a secure WebSocket connection (WSS).

Getting started

Before setting up the integration, ensure you have:

1. Oxylabs account: get your username and password for the Oxylabs Unblocking Browser.

For now, you can get the Unblocking Browser via our sales at [email protected].

1. Node.js: version 18.0.0 or higher (includes npm/npx)

• Windows: download and install from nodejs.org

• macOS: use Homebrew (brew install node) or download from nodejs.org

• Linux:

  • Ubuntu/Debian: sudo apt update && sudo apt install nodejs npm

  • Fedora: sudo dnf install nodejs npm

  • Or download from nodejs.org

1. MCP Host: either Claude Desktop or Cursor installed.

Configure MCP server

Create an MCP server configuration block with your Oxylabs credentials. Replace <username> and <password> with your actual Oxylabs credentials:

"oxylabs_unblocking_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubc.oxylabs.io"
  ]
}

Option 1: integration with Cursor

1. Open Cursor

2. Open Cursor settings

3. Select MCP

4. Add the prepared MCP server configuration

5. Restart Cursor

Option 2: integration with Claude Desktop

1. Open Claude Desktop

2. Open Claude Desktop settings

3. Navigate to Developer

4. Press Edit Config

5. Edit the claude_desktop_config.json file

6. Add the prepared MCP server configuration

7. Restart Claude Desktop

Advanced configuration options

Country selection

You can specify a country for your browser session by adding the ?p_cc parameter to your connection URL:

"oxylabs_unblocking_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubc.oxylabs.io?p_cc=US"
  ]
}

Replace US with your desired SO-3166 country code. If no country is specified, the system will automatically assign one based on availability.

You can find the list of ISO-3166 country codes here.

US-based infrastructure

For users primarily operating in the US, you can connect directly to US-based infrastructure for faster loading times:

"oxylabs_unblocking_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubc-us.oxylabs.io"
  ]
}

This solution primarily shortens the response time for US-based users and should not be confused with proxy geo-location selection.

Browser arguments (Chrome only)

For Chrome-based Unblocking Browser, you can specify additional browser arguments using the bargs parameter:

"oxylabs_unblocking_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubc.oxylabs.io/?bargs=force-color-profile:srgb&bargs=window-position:100,100"
  ]
}

Supported arguments include:

• force-color-profile:<profile>: Force all monitors to be treated as though they have the specified color profile

• window-position:X,Y: Specifies the initial window position

• hide-scrollbars: Prevents creating scrollbars for web content

• enable-features:<feature1>,<feature2>,<feature3>: Comma-separated list of feature names to enable

• disable-notifications: Disables the Web Notification and the Push APIs

Troubleshooting

If you encounter issues with the integration:

1. Connection problems:

   • Verify your Oxylabs credentials

   • Check your network connection

   • Ensure firewalls are not blocking WebSocket connections

2. Performance issues:

   • For US-based users, try the US-specific endpoints

   • Increase timeouts in your configuration if needed

3. Browser not loading:

   • Check Node.js version (must be 18.0.0 or higher)

   • Verify that npx is properly installed

   • Restart the MCP host application