# oxylabs-mcp

> MCP Server

This repository provides an MCP server that allows AI assistants to access web data through Oxylabs' web scraping technology, enabling them to scrape, render, and extract content while bypassing anti-scraping measures.

## Overview

- **Category:** AI
- **Language:** Python
- **Stars:** 101
- **Forks:** 2
- **Owner:** oxylabs
- **GitHub:** https://github.com/oxylabs/oxylabs-mcp
- **Created:** 2025-01-17T13:47:05+00:00
- **Updated:** 2025-03-28T17:21:53+00:00
- **Source:** https://model-context-protocol.com/servers/ai-web-scraping-oxylabs-data-access

## Setup

## Setup

### Install via Smithery (Recommended)

Automatically install Oxylabs MCP server for Claude Desktop via [Smithery](https://smithery.ai/server/@oxylabs/oxylabs-mcp):

```bash
npx -y @smithery/cli install @oxylabs/oxylabs-mcp --client claude
```
---
### Run on Cursor

> [!IMPORTANT]
> Requires Cursor version `0.45.6+`

To configure Oxylabs in Cursor:

1.  Open Cursor **Settings**
2.  Go to **Features > MCP Servers**
3.  Click "**+ Add New MCP Server**"
4.  Enter the following:
    *   **Name**: `oxylabs` (or your preferred name)
    *   **Type**: `command`
    *   **Command**:`npx -y @smithery/cli@latest run @oxylabs/oxylabs-mcp --config "{\"oxylabsUsername\":\"YOUR_USERNAME\",\"oxylabsPassword\":\"YOUR_PASSWORD\"}"`

Replace `your-username` and `your-password` with your Oxylabs credentials.

> [!TIP]
> If you're using Windows and run into issues, try this:
> 
> `cmd /c "set OXYLABS_USERNAME=your-username && set OXYLABS_PASSWORD=your-password && npx -y oxylabs-mcp"`

After that, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Oxylabs when appropriate, but you can explicitly request it by describing your web scraping needs. Access the Composer via `Command+L` (Mac), select "Agent" next to the submit button, and enter your query.

---
### Set up with Claude Desktop

Enable **Developer Mode** and then navigate to **Claude → Settings → Developer → Edit Config** and edit your `claude_desktop_config.json` file as follows:

```json
{
  "mcpServers": {
    "oxylabs_scraper": {
      "command": "uvx",
      "args": ["oxylabs-mcp"],
      "env": {
        "OXYLABS_USERNAME": "YOUR_USERNAME_HERE",
        "OXYLABS_PASSWORD": "YOUR_PASSWORD_HERE"
      }
    }
  }
}
```
---

## 💻 Local/Dev Setup Instructions

### Clone repository

```
git clone <git:url>
```

### Install dependencies

Install MCP server dependencies:

```bash
cd mcp-server-oxylabs

# Create virtual environment and activate it
uv venv

source .venv/bin/activate # MacOS/Linux
# OR
.venv/Scripts/activate # Windows

# Install dependencies
uv sync
```

### Setup with Claude Desktop

Enable **Developer Mode** and then navigate to **Claude → Settings → Developer → Edit Config** and edit your `claude_desktop_config.json` file as follows:

```json
{
  "mcpServers": {
    "oxylabs_scraper": {
      "command": "uv",
      "args": [
        "--directory",
        "/<Absolute-path-to-folder>/oxylabs-mcp",
        "run",
        "oxylabs-mcp"
      ],
      "env": {
        "OXYLABS_USERNAME": "YOUR_USERNAME_HERE",
        "OXYLABS_PASSWORD": "YOUR_PASSWORD_HERE"
      }
    }
  }
}
```
---
### 🐞 Debugging

```bash
make run
```
Then access MCP Inspector at `http://localhost:5173`. You may need to add your username and password as environment variables in the inspector under `OXYLABS_USERNAME` and `OXYLABS_PASSWORD`.

## Tools

## Available Tools

1.  Scrape content from any site (Extract data from any URL, including complex single-page applications).
2.  Automatically get AI-ready data (Automatically clean and convert HTML to Markdown for improved readability).
3.  Bypass blocks & geo-restrictions (Bypass sophisticated bot protection systems with high success rate).
4.  Flexible setup & cross-platform support (Set rendering and parsing options if needed).
5.  Built-in error handling and request management (Comprehensive error handling and reporting).
6.  oxylabs_scraper (Uses Oxylabs Web Scraper API for general website scraping).
7.  oxylabs_web_unblocker (Uses Oxylabs Web Unblocker for hard-to-access websites).