Skip to main content

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:

Credential Header
Web Scraper API token (recommended) Authorization: Bearer <token>
Web Scraper API token (alternative) X-Oxylabs-Api-Token
Web Scraper API username and password Authorization: Basic <base64(username:password)>
Web Scraper API username and password (alt.) X-Oxylabs-Username and X-Oxylabs-Password
AI Studio X-Oxylabs-AI-Studio-Api-Key

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:

Name Description Default
OXYLABS_API_TOKEN Your Oxylabs Web Scraper API token
OXYLABS_USERNAME Your Oxylabs Web Scraper API username
OXYLABS_PASSWORD Your Oxylabs Web Scraper API password
OXYLABS_AI_STUDIO_API_KEY Your Oxylabs AI Studio API key
LOG_LEVEL Log level for the logs returned to the client INFO

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:

Credential How to pass it
Web Scraper API token (recommended) Authorization: Bearer <token>
Web Scraper API token (alternative) X-Oxylabs-Api-Token header
Web Scraper API username and password Authorization: Basic <base64(username:password)> (HTTP Basic auth)
Web Scraper API username and password (alt.) X-Oxylabs-Username and X-Oxylabs-Password headers
AI Studio X-Oxylabs-AI-Studio-Api-Key header

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 Why it matters to you
Manages automated request walls with the Oxylabs global proxy network Enables website access and anonymity
Renders JavaScript in headless Chrome Single‑page apps, sorted
Cleans HTML → Markdown Drop straight into vector DBs or prompts
Optional structured parsers (Google, Amazon, etc.) One‑line access to popular targets

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

image

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

Metadata

Release files for oxylabs-mcp 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oxylabs-mcp 0.10.1
File Size Uploaded Provenance Actions
oxylabs_mcp-0.10.1.tar.gz 152.9 kB With provenance Details for oxylabs_mcp-0.10.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oxylabs-mcp 0.10.1
File Interpreter ABI Platform Actions
oxylabs_mcp-0.10.1-py3-none-any.whl Python 3 none any Details for oxylabs_mcp-0.10.1-py3-none-any.whl

Total release size: 172.5 kB

Release files / oxylabs_mcp-0.10.1.tar.gz

Download URL oxylabs_mcp-0.10.1.tar.gz
Size 152.9 kB
Tags Source
SHA-256 checksum
How to use checksums
7cac0b03f19f030584c60bc9e2a14c61284667a219a287152504c3a44f23270a
BLAKE2b-256 checksum
How to use checksums
8103b16412914158acd8e0afc0b9f1724850dc560cd62638205939d1664164aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / oxylabs_mcp-0.10.1-py3-none-any.whl

Download URL oxylabs_mcp-0.10.1-py3-none-any.whl
Size 19.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fc6545f1a85cf38de2d9e66b4106291fd1405d50d61912369940cb4eaa55e2eb
BLAKE2b-256 checksum
How to use checksums
241298d895891e9760f6f961d37a55779292c6007803db05130a71d408928705
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for oxylabs-mcp 0.10.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for oxylabs_mcp-0.10.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.10.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page