io.oxylabs/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-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",
        "/<absolute-path-to-folder>/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:

🛡️ 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.

Made with ☕ by Oxylabs. Feel free to give us a ⭐ and a follow if our MCP saved you a weekend.

Solutions made based on this MCP:

Michelin Detour