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:
Oxylabs account: get your username and password for the Oxylabs Unblocking Browser.
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.orgLinux:
Ubuntu/Debian:
sudo apt update && sudo apt install nodejs npm
Fedora:
sudo dnf install nodejs npm
Or download from nodejs.org
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
Open Cursor
Open Cursor settings
Select MCP
Add the prepared MCP server configuration
Restart Cursor
Option 2: integration with Claude Desktop
Open Claude Desktop
Open Claude Desktop settings
Navigate to Developer
Press Edit Config
Edit the
claude_desktop_config.json
fileAdd the prepared MCP server configuration
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 profilewindow-position:X,Y
: Specifies the initial window positionhide-scrollbars
: Prevents creating scrollbars for web contentenable-features:<feature1>,<feature2>,<feature3>
: Comma-separated list of feature names to enabledisable-notifications
: Disables the Web Notification and the Push APIs
Troubleshooting
If you encounter issues with the integration:
Connection problems:
Verify your Oxylabs credentials
Check your network connection
Ensure firewalls are not blocking WebSocket connections
Performance issues:
For US-based users, try the US-specific endpoints
Increase timeouts in your configuration if needed
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
Last updated
Was this helpful?