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.

📖 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 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

5. ai_scraper: scrapes content from any URL with AI-powered extraction, in JSON, CSV, Markdown, or TOON format;

6. ai_crawler: crawls a website from a starting URL based on a prompt and collects data across multiple pages;

7. ai_browser_agent: controls a real browser based on a prompt — navigates, clicks, fills forms — and returns the result;

8. ai_search: searches the web and optionally returns Markdown content of each result;

9. ai_map: maps a website's URLs, filtered by keywords or a prompt;

10. 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 your username and password from Oxylabs (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:

Setup with Claude Code:

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"

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

{
  "mcpServers": {
    "oxylabs": {
      "url": "https://mcp.oxylabs.io/mcp",
      "headers": {
        "Authorization": "Basic ",
        "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:

Based on the provided credentials, the server automatically exposes the corresponding tools:

• If only `OXYLABS_USERNAME` and `OXYLABS_PASSWORD` are provided, the server exposes the Web Scraper API tools;
• If only `OXYLABS_AI_STUDIO_API_KEY` is provided, the server exposes the AI Studio tools;
• If all three are provided, the server exposes all tools.

❗ **Important: only set the environment variables you have real credentials for.

Leaving placeholder values will result in exposed tools that do not work.**

Configure with uvx

Installs the package from PyPI and runs it automatically:

{
  "mcpServers": {
    "oxylabs": {
      "command": "uvx",
      "args": ["oxylabs-mcp"],
      "env": {
        "OXYLABS_USERNAME": "YOUR_USERNAME",
        "OXYLABS_PASSWORD": "YOUR_PASSWORD",
        "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_USERNAME": "YOUR_USERNAME",
        "OXYLABS_PASSWORD": "YOUR_PASSWORD",
        "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": "Basic ",
        "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:

🛡️ License

Distributed under the MIT License – see LICENSE for details.

About Oxylabs

Established in 2015, Oxylabs is a market-leading web intelligence collection

platform, driven by the highest business, ethics, and compliance standards,

enabling companies worldwide to unlock data-driven insights.

mcp-name: io.oxylabs/oxylabs-mcp

Solutions made based on this MCP:

Michelin Detour