# 📖 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, bypass anti-scraping measures, and access geo-restricted web data from 195+ countries.

# 🛠️ MCP Tools

Oxylabs MCP provides two sets of tools that can be used together or independently:

# # Oxylabs Web Scraper API Tools

1. universal_scraper: Uses Oxylabs Web Scraper API for general website scraping;
2. google_search_scraper: Uses Oxylabs Web Scraper API to extract results from Google Search;
3. amazon_search_scraper: Uses Oxylabs Web Scraper API to scrape Amazon search result pages;
4. amazon_product_scraper: Uses Oxylabs Web Scraper API to extract data from individual Amazon product pages.

# # Oxylabs AI Studio Tools

1. ai_scraper: Scrape content from any URL in JSON or Markdown format with AI-powered data extraction;
2. ai_crawler: Based on a prompt, crawls a website and collects data in Markdown or JSON format across multiple pages;
3. ai_browser_agent: Based on prompt, controls a browser and returns data in Markdown, JSON, HTML, or screenshot formats;
4. ai_search: Search the web for URLs and their contents with AI-powered content extraction.

# ✅ Prerequisites

Before you begin, make sure you have at least one of the following:

• Oxylabs Web Scraper API Account: Obtain your username and password from Oxylabs (1-week free trial available);
• Oxylabs AI Studio API Key: Obtain your API key from Oxylabs AI Studio. (1000 credits free).

# 📦 Configuration

# # Environment variables

Oxylabs MCP server supports the following environment variables:
| Name | Description | Default |
|- -- -- -- -- -- -- -- -- -- -- -- -- -- -|- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --|- -- -- -- --|
| 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 |

Based on provided credentials, the server will automatically expose the corresponding tools:

• If only OXYLABS_USERNAME and OXYLABS_PASSWORD are provided, the server will expose the Web Scraper API tools;
• If only OXYLABS_AI_STUDIO_API_KEY is provided, the server will expose the AI Studio tools;
• If both OXYLABS_USERNAME and OXYLABS_PASSWORD and OXYLABS_AI_STUDIO_API_KEY are provided, the server will expose all tools.

❗❗❗ Important note: if you don't have Web Scraper API or Oxylabs AI studio credentials, delete the corresponding environment variables placeholders.
Leaving placeholder values will result in exposed tools that do not work.

# # Configure with uvx

• Install the uvx package manager:

  #  macOS and Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  OR:

  #  Windows
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

• Use the following config:

  {
    "mcpServers": {
      "oxylabs": {
        "command": "uvx",
        "args": ["oxylabs-mcp"],
        "env": {
          "OXYLABS_USERNAME": "OXYLABS_USERNAME",
          "OXYLABS_PASSWORD": "OXYLABS_PASSWORD",
          "OXYLABS_AI_STUDIO_API_KEY": "OXYLABS_AI_STUDIO_API_KEY"
        }
      }
    }
  }
  

# # Configure with uv

• Install the uv package manager:

  #  macOS and Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  OR:

  #  Windows
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

• Use the following config:

  {
    "mcpServers": {
      "oxylabs": {
        "command": "uv",
        "args": [
          "- -directory",
          "/<Absolute-path-to-folder>/oxylabs-mcp",
          "run",
          "oxylabs-mcp"
        ],
        "env": {
          "OXYLABS_USERNAME": "OXYLABS_USERNAME",
          "OXYLABS_PASSWORD": "OXYLABS_PASSWORD",
          "OXYLABS_AI_STUDIO_API_KEY": "OXYLABS_AI_STUDIO_API_KEY"
        }
      }
    }
  }
  

# # Configure with Smithery Oauth2

• Go to https://smithery.ai/server/@oxylabs/oxylabs-mcp;
• Click Auto to install the Oxylabs MCP configuration for the respective client;
• OR use the following config:

  {
    "mcpServers": {
      "oxylabs": {
        "url": "https://server.smithery.ai/@oxylabs/oxylabs-mcp/mcp"
      }
    }
  }

• Follow the instructions to authenticate Oxylabs MCP with Oauth2 flow

# # Configure with Smithery query parameters

In case your client does not support the Oauth2 authentication, you can pass the Oxylabs authentication parameters directly in url

  {
    "mcpServers": {
      "oxylabs": {
        "url": "https://server.smithery.ai/@oxylabs/oxylabs-mcp/mcp?oxylabsUsername=OXYLABS_USERNAME&oxylabsPassword=OXYLABS_PASSWORD&oxylabsAiStudioApiKey=OXYLABS_AI_STUDIO_API_KEY"
      }
    }
  }

# # Manual 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.

# # Manual 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

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"
  }
}

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

# ✨ 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

• Bypass sophisticated bot protection 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.
MCP (Multi‑Client Proxy) makes that happen by doing the boring parts for you:

| What Oxylabs MCP does | Why it matters to you |
|- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --|- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -|
| Bypasses anti‑bot walls with the Oxylabs global proxy network | Keeps you unblocked and anonymous |
| Renders JavaScript in headless Chrome | Single‑page apps, sorted |
| Cleans HTML → JSON | Drop straight into vector DBs or prompts |
| Optional structured parsers (Google, Amazon, etc.) | One‑line access to popular targets |

mcp-name: io.oxylabs/oxylabs-mcp