Oxylabs MCP

Oxylabs MCP Server

The missing link between AI models and the real‑world web: one API that delivers clean, structured data from any site.

---

Disclaimer

This repository is still fully supported, but if you are using Oxylabs Web API please refer to Web API MCP repository: Web API MCP

📖 Overview

The Oxylabs MCP server provides a bridge between AI models and the web. It enables them to scrape any URL, render JavaScript-heavy pages, extract and format content for AI use, manage CAPTCHA, and access geo-restricted web data from 195+ countries.

It is built on the Model Context Protocol (MCP), the open standard for connecting AI assistants to external tools and data.

mcp-name: io.oxylabs/oxylabs-mcp

🛠️ MCP Tools

Oxylabs MCP provides two sets of tools that can be used together or independently:

Oxylabs Web Scraper API tools

1. universal_scraper: scrapes any URL, with optional JavaScript rendering, geo-targeting, and Markdown/HTML/links output;
2. google_search_scraper: extracts results from Google Search, with optional parsing into structured JSON;
3. amazon_search_scraper: scrapes Amazon search result pages, with optional parsing into structured JSON;
4. amazon_product_scraper: extracts data from individual Amazon product pages.

Oxylabs AI Studio tools

1. ai_scraper: scrapes content from any URL with AI-powered extraction, in JSON, CSV, Markdown, or TOON format;
2. ai_crawler: crawls a website from a starting URL based on a prompt and collects data across multiple pages;
3. ai_browser_agent: controls a real browser based on a prompt — navigates, clicks, fills forms — and returns the result;
4. ai_search: searches the web and optionally returns Markdown content of each result;
5. ai_map: maps a website's URLs, filtered by keywords or a prompt;
6. generate_schema: generates an OpenAPI-format JSON schema for structured extraction with the AI tools above.

✅ Prerequisites

Before you begin, make sure you have at least one of the following:

• Oxylabs Web Scraper API account: obtain an API token (or your username and password) from the Oxylabs dashboard (1-week free trial available);
• Oxylabs AI Studio API key: obtain your API key from Oxylabs AI Studio (1000 credits free).

To run the server locally (Option 2 below) you will also need the uv package manager:

# macOS and Linux

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

# Windows

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

📦 Configuration

There are two ways to use the server: connect to the hosted instance (no installation) or run it locally with credentials in environment variables.

Option 1: Hosted server (no installation)

Oxylabs runs a hosted MCP server at:

https://mcp.oxylabs.io/mcp

Credentials are passed with request headers:

If both an API token and a username and password are passed, the token is used.

Setup with Claude Code:

claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \

--header "Authorization: Bearer YOUR_API_TOKEN" \ --header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"

Setup with Cursor or any client that supports remote MCP servers with custom headers:

{

"mcpServers": { "oxylabs": { "url": "https://mcp.oxylabs.io/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN", "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY" } } } }

The server is also listed on Smithery.

Note: clients that only support OAuth for remote servers (for example, adding a custom

connector in the claude.ai web UI) cannot pass headers yet — OAuth sign-in is on our roadmap.

Use the local setup below with those clients in the meantime.

Option 2: Run locally

Environment variables

Oxylabs MCP server supports the following environment variables:

For the Web Scraper API tools, set either OXYLABS_API_TOKEN or both OXYLABS_USERNAME and OXYLABS_PASSWORD. If both are set, the token is used. For the AI Studio tools, set OXYLABS_AI_STUDIO_API_KEY.

All tools are always listed; calling a tool without the credentials it needs returns an error message explaining what to configure.

❗ Important: only set the environment variables you have real credentials for. Placeholder values make tool calls fail.

Configure with uvx

Installs the package from PyPI and runs it automatically:

{

"mcpServers": { "oxylabs": { "command": "uvx", "args": ["oxylabs-mcp"], "env": { "OXYLABS_API_TOKEN": "YOUR_API_TOKEN", "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY" } } } }

Configure with a local checkout

Useful for development — runs the server from a local clone of this repository:

{

"mcpServers": { "oxylabs": { "command": "uv", "args": [ "--directory", "/ /oxylabs-mcp", "run", "oxylabs-mcp" ], "env": { "OXYLABS_API_TOKEN": "YOUR_API_TOKEN", "OXYLABS_AI_STUDIO_API_KEY": "YOUR_API_KEY" } } } }

Running as a remote HTTP server (self-hosting)

The server also supports the MCP streamable-HTTP transport. Start it with:

MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 uvx oxylabs-mcp

With the HTTP transport, credentials are passed per request instead of environment variables:

Example client configuration:

{

"mcpServers": { "oxylabs": { "url": "https://your-host:8000/mcp", "headers": { "Authorization": "Bearer YOUR_API_TOKEN", "X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY" } } } }

All tools are always listed regardless of provided credentials; calling a tool without the credentials it needs returns an error message explaining exactly what to configure.

Setup with Claude Desktop

Navigate to Claude → Settings → Developer → Edit Config and add one of the configurations above to the claude_desktop_config.json file.

Setup with Cursor AI

Navigate to Cursor → Settings → Cursor Settings → MCP. Click Add new global MCP server and add one of the configurations above.

📝 Logging

The server provides additional information about the tool calls in notification/message events:

{

"method": "notifications/message", "params": { "level": "info", "data": "Create job with params: {\"url\": \"https://ip.oxylabs.io\"}" } }

{

"method": "notifications/message", "params": { "level": "info", "data": "Job info: job_id=7333113830223918081 job_status=done" } }

{

"method": "notifications/message", "params": { "level": "error", "data": "Error: request to Oxylabs API failed" } }

✨ Key Features

Scrape content from any site

• Extract data from any URL, including complex single-page applications
• Fully render dynamic websites using headless browser support
• Choose full JavaScript rendering, HTML-only, or none
• Emulate Mobile and Desktop viewports for realistic rendering

Automatically get AI-ready data

• Automatically clean and convert HTML to Markdown for improved readability
• Use automated parsers for popular targets like Google, Amazon, and more

Manage CAPTCHA & geo-restrictions

• Navigate sophisticated automated request management systems with high success rate
• Reliably scrape even the most complex websites
• Get automatically rotating IPs from a proxy pool covering 195+ countries

Flexible setup & cross-platform support

• Set rendering and parsing options if needed
• Feed data directly into AI models or analytics tools
• Works on macOS, Windows, and Linux

Built-in error handling and request management

• Comprehensive error handling and reporting
• Smart rate limiting and request management

Why Oxylabs MCP? 🕸️ ➜ 📦 ➜ 🤖

Imagine telling your LLM *"Summarise the latest Hacker News discussion about GPT‑5"* – and it simply answers. The Oxylabs MCP server makes that happen by doing the boring parts for you:

| What Oxylabs MCP does