oxylabs-mcp

Purpose

Oxylabs MCP is an MCP (Model Context Protocol) server officially launched by Oxylabs, designed to build a bridge between AI models and the real web. It enables AI assistants to scrape any URL, render JavaScript-heavy pages, extract and format content for AI use, manage CAPTCHAs, and access geo-restricted web data from 195+ countries/regions.

Main Capabilities

Oxylabs MCP provides two sets of tools, which can be used together or independently.

Oxylabs Web Scraper API Tools

universal_scraper: Scrape any URL, with optional JavaScript rendering, geolocation, and Markdown/HTML/link output;
google_search_scraper: Extract results from Google Search, with optional parsing into structured JSON;
amazon_search_scraper: Scrape Amazon search results pages, with optional parsing into structured JSON;
amazon_product_scraper: Extract data from a single Amazon product page.

Oxylabs AI Studio Tools

ai_scraper: Scrape the content of any URL using AI-powered extraction, supporting JSON, CSV, Markdown, or TOON formats;
ai_crawler: Crawl a website from a starting URL based on a prompt, and collect data across multiple pages;
ai_browser_agent: Control a real browser based on a prompt—navigate, click, fill out forms—and return results;
ai_search: Search the web, with optional return of Markdown content for each result;
ai_map: Map a website's URLs, filterable by keyword or prompt;
generate_schema: Generate an OpenAPI-format JSON schema for the above AI tools, for structured extraction.

How to Use

Prerequisites

Before starting, you need at least one of the following:

An Oxylabs Web Scraper API account: Obtain a username and password from Oxylabs (a 1-week free trial is available);
Oxylabs AI Studio API key: Get an API key from Oxylabs AI Studio (1000 free credits). To run the server locally (option two), the uv package manager is also required.

Configuration

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

Option One: Hosted Server (No Installation Required)

Oxylabs runs a hosted MCP server. Credentials are passed via request headers.

Set up using Claude Code;
Set up using Cursor or any client that supports remote MCP servers with custom request headers;
This server is also listed on Smithery. Note: Remote server clients that only support OAuth (for example, adding a custom connector in the claude.ai web interface) cannot yet pass request headers—OAuth login is on our roadmap. In the meantime, please use the local setup below for these clients.

Option Two: Run Locally

The Oxylabs MCP server supports the following environment variables. Based on the credentials provided, the server automatically exposes the corresponding tools:

If only OXYLABS_USERNAME and OXYLABS_PASSWORD are provided, the server exposes Web Scraper API tools;
If only OXYLABS_AI_STUDIO_API_KEY is provided, the server exposes AI Studio tools;
If all three are provided, the server exposes all tools. Important: only set environment variables for which you have real credentials. Leaving placeholder values will cause the exposed tools to not work.

Install the package from PyPI and run it automatically; or for development—clone this repository locally and run the server. The server also supports MCP streaming HTTP transport. When using HTTP transport, credentials are passed per request rather than via environment variables.

Regardless of the credentials provided, all tools are always listed; calling a tool that lacks the required credentials returns an error message explaining what needs to be configured.

Client Setup

Claude: Navigate to Claude → Settings → Developer → Edit Config, and add one of the above configurations to the claude_desktop_config.json file;
Cursor: Navigate to Cursor → Settings → Cursor Settings → MCP, clickClick to add a new global MCP server, and add one of the above configurations.

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

Use cases

Extract data from any URL, including complex single-page applications;
Fully render dynamic websites with headless browser support;
Choose full JavaScript rendering, HTML only, or no rendering;
Simulate mobile and desktop viewports for realistic rendering;
Automatically clean and convert HTML to Markdown for improved readability;
Use automatic parsers for popular targets such as Google, Amazon, and more;
Handle complex automated request management systems and maintain a high success rate;
Reliably scrape even the most complex websites;
Get automatically rotating IPs from a proxy pool covering 195+ countries/regions;
Set rendering and parsing options as needed;
Feed data directly into AI models or analysis tools.

Limitations

Requires Oxylabs credentials: a Web Scraper API account (username and password) or an AI Studio API key, otherwise the tool will not work;
Running locally requires installing the uv package manager;
OAuth-only remote server clients cannot currently pass request headers, so local setup must be used instead;
If a required credential is missing when a tool is called, an error message is returned.

Platform support

Supports macOS, Windows, and Linux. Includes comprehensive error handling and reporting, as well as intelligent rate limiting and request management.

Why choose Oxylabs MCP?

Imagine telling your LLM "summarize the latest Hacker News discussion about GPT-5" - it answers directly. The Oxylabs MCP server makes this possible by doing the boring parts for you.

License

Distributed under the MIT License - see LICENSE for details.

Founded in 2015, Oxylabs is a market-leading web intelligence collection platform that upholds the highest commercial, ethical, and compliance standards, helping companies worldwide unlock data-driven insights.

mcp-name: io.oxylabs/oxylabs-mcp

Solution built on this MCP: Michelin Detour.

Official Oxylabs MCP integration.