📖 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/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
- 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:
🛡️ 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.
