Model Context Protocol (MCP)

Use Oxylabs MCP to give AI assistants live web scraping, search, and extraction tools via Web Scraper API and AI Studio.

The Oxylabs MCP server connects AI assistants (Claude, Cursor, and any other Model Context Protocol client) to the real-world web.

Once connected, your assistant can scrape any URL (includes JavaScript rendering and geo-targeting), search the web, crawl sites, and extract structured data.

Open source & registry: View the source code on GitHub. The server is officially registered on the MCP Registry (io.oxylabs/oxylabs-mcp), PyPI, and Smithery.

Prerequisites

You need at least one credential set to unlock its corresponding tools. Providing both unlocks all tools listed below.

Credentials	Where to get it	Unlocks
Web Scraper API username & password	Oxylabs dashboard (free trial available)	Web Scraper API tools
AI Studio API key	AI Studio Settings (free credits included)	AI Studio tools

Only configure credentials you actually have. Placeholder values expose tools that will fail when called.

Available tools

Tool	What it does	Requires
universal_scraper	Scrapes any URL. Optional JavaScript rendering, geo-targeting, Markdown/HTML output	Web Scraper API
google_search_scraper	Google Search results, optionally parsed to structured JSON	Web Scraper API
amazon_search_scraper	Amazon search result pages, optionally parsed	Web Scraper API
amazon_product_scraper	Individual Amazon product pages	Web Scraper API
ai_scraper	AI-powered extraction from any URL (JSON, CSV, Markdown, TOON)	AI Studio
ai_crawler	Prompt-driven multi-page crawling and data collection	AI Studio
ai_browser_agent	Prompt-driven browser control: navigate, click, fill forms	AI Studio
ai_search	Web search with optional Markdown content of each result	AI Studio
ai_map	Maps website URLs	AI Studio
generate_schema	Generates custom extraction schemas for the AI Studio tools	AI Studio

Choose how to connect

	Hosted server (recommended)	Local server
Install	None	uv + uvx oxylabs-mcp
Endpoint	https://mcp.oxylabs.io/mcp	Cursor/Claude spawn the process
Credentials	HTTP headers	Environment variables
Best for	Quickest setup, no management	Offline control, local debugging, clients that cannot send custom headers

Method 1: Hosted server (recommended)

Connect to Oxylabs hosted MCP server:

https://mcp.oxylabs.io/mcp

Pass credentials as request headers:

Credential	Header
Web Scraper API	Authorization: Basic <base64(username:password)>
AI Studio	X-Oxylabs-AI-Studio-Api-Key: <your API key>

Note: Include only the headers for credentials you have.

Claude Code

Install directly in the command line:

claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  --header "Authorization: Basic $(echo -n 'YOUR_USERNAME:YOUR_PASSWORD' | base64)" \
  --header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"

Omit a --header line if you do not have that credential.

Claude Desktop

Claude Desktop built-in config editor uses local (command) servers. For the hosted endpoint, use Claude Code with the HTTP command above, or run the server locally and point Claude Desktop at that config.

Cursor

1. Open Cursor Settings → Customize in the sidebar → MCPs
2. Click + New
3. Choose User (all projects) or Project (workspace only)
4. Add the following to the opened mcp.json:

   {
     "mcpServers": {
       "oxylabs": {
         "url": "https://mcp.oxylabs.io/mcp",
         "headers": {
           "Authorization": "Basic <base64 of username:password>",
           "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
         }
       }
     }
   }

5. Save, then confirm the server is enabled under Customize → MCPs.

Note: User writes to ~/.cursor/mcp.json. Workspace writes to .cursor/mcp.json in the chosen workspace. If both define the same server name, the workspace config takes priority.

Method 2: Local server

The server is available on our PyPI repository.

If not installed yet, install the uv package according to the chosen operating system:

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Credentials are passed as environment variables (set only the ones you have):

Variable	Description
OXYLABS_USERNAME	Web Scraper API username
OXYLABS_PASSWORD	Web Scraper API password
OXYLABS_AI_STUDIO_API_KEY	AI Studio API key

Claude Code

claude mcp add oxylabs -- command uvx args oxylabs-mcp \
  --env OXYLABS_USERNAME=YOUR_USERNAME \
  --env OXYLABS_PASSWORD=YOUR_PASSWORD \
  --env OXYLABS_AI_STUDIO_API_KEY=YOUR_API_KEY

Manual config path for Claude Code: ~/.config/claude/mcp.json (macOS/Linux) or %USERPROFILE%\.config\claude\mcp.json (Windows). The JSON shape matches Claude Desktop.

Claude Desktop

1. Open Claude → Settings → Developer → Edit Config
2. Add the following to claude_desktop_config.json:

   {
     "mcpServers": {
       "oxylabs": {
         "command": "uvx",
         "args": ["oxylabs-mcp"],
         "env": {
           "OXYLABS_USERNAME": "YOUR_USERNAME",
           "OXYLABS_PASSWORD": "YOUR_PASSWORD",
           "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }

3. Restart Claude Desktop

Cursor

1. Open Cursor Settings → Customize in the sidebar → MCPs
2. Click + New
3. Choose User (all projects) or Project (workspace only)
4. Add the following to the opened mcp.json:

   {
     "mcpServers": {
       "oxylabs": {
         "command": "uvx",
         "args": ["oxylabs-mcp"],
         "env": {
           "OXYLABS_USERNAME": "YOUR_USERNAME",
           "OXYLABS_PASSWORD": "YOUR_PASSWORD",
           "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }

5. Save, then confirm the server is enabled under Customize → MCPs.

Note: User writes to ~/.cursor/mcp.json. Workspaces writes to .cursor/mcp.json in the chosen workspace. If both define the same server name, the workspace config takes priority.

Verify the setup

After connecting, ask your assistant something that requires live web data (e.g. “Scrape https://ip.oxylabs.io and return the content as Markdown.”):

1

Confirm the oxylabs server appears and is enabled in your client’s MCP list.

2

Approve the tool call when prompted (clients ask before running MCP tools by default).

3

If the call fails, check credentials and client logs (Cursor: Output → MCP Logs).

Troubleshooting

Error	Solution
Server missing from the client	Restart the app after editing config. Confirm JSON is valid.
Tools listed but calls fail	Placeholder credentials, wrong Base64, or missing header/env for that tool.
Hosted URL won’t connect	Client may not support custom headers, use local setup.
uvx / command not found	Install uv and ensure it is on your PATH.
Cursor UI path looks different	Skip the UI and edit mcp.json directly (labels can change between Cursor versions).

For issues or feature requests, open a GitHub issue or contact 24/7 Oxylabs support at [e-mail].