Oxylabs MCP Server
OfficialUse Oxylabs MCP to scrape, search, crawl, map, browse, and extract structured web data for AI-assisted workflows.
Scrape any URL with optional JavaScript rendering, geo-targeting, CAPTCHA/request management, and Markdown/HTML/links output.
Scrape Google Search and Amazon search/product pages, with optional parsed structured JSON and locale/domain/currency options.
Use AI Studio scraping to extract JSON/CSV/Markdown/TOON from pages, with JSON schema support.
Crawl sites from a start URL using a prompt, return limited sources, and optionally render JavaScript.
Run an AI browser agent to navigate, click, fill forms, scroll, and return results in multiple formats.
Search the web with optional markdown content for each result.
Map website URLs with keyword/prompt filters, crawl depth, subdomain/external domain options.
Generate OpenAPI-format JSON schemas for structured extraction with crawler/scraper/browser-agent tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Oxylabs MCP Server scrape the latest iPhone reviews from Amazon and summarize them"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Decodo MCP Server
📖 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
universal_scraper: scrapes any URL, with optional JavaScript rendering, geo-targeting, and Markdown/HTML/links output;
google_search_scraper: extracts results from Google Search, with optional parsing into structured JSON;
amazon_search_scraper: scrapes Amazon search result pages, with optional parsing into structured JSON;
amazon_product_scraper: extracts data from individual Amazon product pages.
Oxylabs AI Studio tools
ai_scraper: scrapes content from any URL with AI-powered extraction, in JSON, CSV, Markdown, or TOON format;
ai_crawler: crawls a website from a starting URL based on a prompt and collects data across multiple pages;
ai_browser_agent: controls a real browser based on a prompt — navigates, clicks, fills forms — and returns the result;
ai_search: searches the web and optionally returns Markdown content of each result;
ai_map: maps a website's URLs, filtered by keywords or a prompt;
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/mcpCredentials are passed with request headers:
Credential | Header |
Web Scraper API token (recommended) |
|
Web Scraper API token (alternative) |
|
Web Scraper API username and password |
|
Web Scraper API username and password (alt.) |
|
AI Studio |
|
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 |
| Your Oxylabs Web Scraper API token | |
| Your Oxylabs Web Scraper API username | |
| Your Oxylabs Web Scraper API password | |
| Your Oxylabs AI Studio API key | |
| Log level for the logs returned to the client |
|
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-mcpWith the HTTP transport, credentials are passed per request instead of environment variables:
Credential | How to pass it |
Web Scraper API token (recommended) |
|
Web Scraper API token (alternative) |
|
Web Scraper API username and password |
|
Web Scraper API username and password (alt.) |
|
AI Studio |
|
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
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 clean and convert HTML to Markdown for improved readability
Use automated parsers for popular targets like Google, Amazon, and more
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
Set rendering and parsing options if needed
Feed data directly into AI models or analytics tools
Works on macOS, Windows, and Linux
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.

Solutions made based on this MCP:
Available Tools
10 toolsai_browser_agentCRead-onlyInspect
Run the browser agent and return the data in the specified format.
This tool is useful if you need navigate around the website and do some actions. It allows navigating to any url, clicking on links, filling forms, scrolling, etc. Finally it returns the data in the specified format. Schema is required only if output_format is json, csv or toon. 'task_prompt' describes what browser agent should achieve
Inputs: url (required), task_prompt (required), schema, geo_location, +1 more. Returns: result
ai_crawlerCRead-onlyInspect
Tool useful for crawling a website from starting url and returning data in a specified format.
Schema is required only if output_format is json, csv or toon. 'render_javascript' is used to render javascript heavy websites. 'return_sources_limit' is used to limit the number of sources to return, for example if you expect results from single source, you can set it to 1.
Inputs: url (required), user_prompt (required), schema, geo_location, +3 more. Returns: result
ai_mapDRead-onlyInspect
Tool useful for mapping website's URLs.
Inputs: url (required), limit, user_prompt, geo_location, +5 more. Returns: result
ai_scraperARead-onlyInspect
Scrape the contents of the web page and return the data in the specified format.
Schema is required only if output_format is json or csv. 'render_javascript' is used to render javascript heavy websites.
Inputs: url (required), schema, geo_location, output_format, +1 more. Returns: result
ai_searchARead-onlyInspect
Search the web based on a provided query.
'return_content' is used to return markdown content for each search result. If 'return_content' is set to True, you don't need to use ai_scraper to get the content of the search results urls, because it is already included in the search results. if 'return_content' is set to True, prefer lower 'limit' to reduce payload size.
Inputs: query (required), limit, geo_location, return_content, +1 more. Returns: result
amazon_product_scraperARead-onlyInspect
Scrape Amazon products.
Supports content parsing, different user agent types, domain, geolocation, locale parameters and different output formats. Supports Amazon specific parameters such as currency and getting more accurate pricing data with auto select variant.
Inputs: query (required), parse, domain, locale, +6 more. Returns: result
amazon_search_scraperBRead-onlyInspect
Scrape Amazon search results.
Supports content parsing, different user agent types, pagination, domain, geolocation, locale parameters and different output formats. Supports Amazon specific parameters such as category id, merchant id, currency.
Inputs: query (required), pages, parse, domain, +9 more. Returns: result
generate_schemaCRead-onlyInspect
Generate a json schema in openapi format.
Inputs: app_name (required), user_prompt (required). Returns: result
google_search_scraperARead-onlyInspect
Scrape Google Search results.
Supports content parsing, different user agent types, pagination, domain, geolocation, locale parameters and different output formats.
Inputs: query (required), limit, pages, parse, +8 more. Returns: result
universal_scraperBRead-onlyInspect
Get a content of any webpage.
Supports browser rendering, parsing of certain webpages and different output formats.
Inputs: url (required), render, geo_location, output_format, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Several tools have heavily overlapping purposes: ai_scraper and universal_scraper both claim to scrape any webpage content, while ai_crawler and ai_browser_agent both navigate websites and extract data. ai_search and google_search_scraper also cover similar territory, making selection ambiguous without very careful reading.
Names are descriptive and readable, but they follow two different conventions: an ai_ prefix group (ai_crawler, ai_scraper, ai_search, ai_map, ai_browser_agent) and a target_suffix group (google_search_scraper, amazon_search_scraper, amazon_product_scraper, universal_scraper). Only generate_schema stands apart with a clear verb_noun pattern.
Ten tools is well-scoped for a web scraping and search server covering generic scraping, search, browser automation, URL mapping, schema generation, and Amazon-specific extraction. Each tool represents a distinct product capability, even if some overlap exists.
The tool surface covers the core needs of the domain: general search, Google-specific search, generic page scraping, crawling, browser-driven interaction, site mapping, and Amazon search/product scraping. There are no obvious dead ends for common web data acquisition workflows.
Maintenance
Related MCP Connectors
Fetch and extract data from any public web page, even JS-rendered or anti-bot protected
Scraping API for Google Search, Maps, Flights, Jobs, YouTube, LinkedIn, Trustpilot and more.
Oxylabs MCP — Oxylabs Web Scraper API (oxylabs.io)
Scrape any website, extract structured data, and collect web content at scale with AI agents
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables web scraping and document processing with JavaScript execution, anti-detection measures, batch processing, and structured data extraction. Supports multiple formats including markdown, HTML, screenshots, and handles PDFs with OCR capabilities.44 PyPI4MIT
- AlicenseAqualityBmaintenanceEnables web scraping and data extraction from websites with geographic flexibility, privacy features, and anti-detection capabilities. Supports scraping general websites, Google Search, Amazon Search, and Reddit with customizable parameters for rendering, geolocation, and locale.33859 npm41ISC
- AlicenseAqualityDmaintenanceEnables AI agents to scrape any website by providing tools for JavaScript rendering, antibot bypass, and automatic captcha solving. It supports synchronous, asynchronous, and batch scraping operations with built-in proxy rotation.535 PyPIMIT
- AlicenseAqualityAmaintenanceEnables web scraping, structured data extraction, and screenshot capture with automatic anti-bot bypass, supporting JavaScript rendering, proxy rotation, and tiered pricing.262,618 npm2MIT