Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/oxylabs/oxylabs-mcp


https://github.com/oxylabs/oxylabs-mcp

Last synced: 9 months ago
JSON representation

Awesome Lists containing this project

README 

          


  Oxylabs + MCP





  Oxylabs MCP Server






  The missing link between AI models and the real‑world web: one API that delivers clean, structured data from any site.







[![smithery badge](https://smithery.ai/badge/@oxylabs/oxylabs-mcp)](https://smithery.ai/server/@oxylabs/oxylabs-mcp)

[![pypi package](https://img.shields.io/pypi/v/oxylabs-mcp?color=%2334D058&label=pypi%20package)](https://pypi.org/project/oxylabs-mcp/)

[![](https://dcbadge.vercel.app/api/server/eWsVUJrnG5?style=flat)](https://discord.gg/Pds3gBmKMH)

[![Licence](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/f6a9c0bc-83a6-4f78-89d9-f2cec4ece98d)

![Coverage badge](https://raw.githubusercontent.com/oxylabs/oxylabs-mcp/coverage/coverage-badge.svg)








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



This implementation leverages the Model Context Protocol (MCP) to create a secure, standardized way for AI assistants to interact with web content.



---



## Why Oxylabs MCP?  🕸️ ➜ 📦 ➜ 🤖



Imagine telling your LLM *"Summarise the latest Hacker News discussion about GPT‑7"* – 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       |



## ✨ Key Features



 Scrape content from any site





- 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 get AI-ready data





- Automatically clean and convert HTML to Markdown for improved readability

- Use automated parsers for popular targets like Google, Amazon, and etc.



 Bypass blocks & geo-restrictions





- 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



 Flexible setup & cross-platform support





- Set rendering and parsing options if needed

- Feed data directly into AI models or analytics tools

- Works on macOS, Windows, and Linux



 Built-in error handling and request management





- Comprehensive error handling and reporting

- Smart rate limiting and request management



---



## 🛠️ MCP Tools



Oxylabs MCP provides the following 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.



## 💡 Example Queries

When you've set up the MCP server with **Claude**, you can make requests like:



- Could you scrape `https://www.google.com/search?q=ai` page?

- Scrape `https://www.amazon.de/-/en/Smartphone-Contract-Function-Manufacturer-Exclusive/dp/B0CNKD651V` with **parse** enabled

- Scrape `https://www.amazon.de/-/en/gp/bestsellers/beauty/ref=zg_bs_nav_beauty_0` with **parse** and **render** enabled

- Use web unblocker with **render** to scrape `https://www.bestbuy.com/site/top-deals/all-electronics-on-sale/pcmcat1674241939957.c`



---



## ✅ Prerequisites



Before you begin, make sure you have:



- **Oxylabs Account**: Obtain your username and password from [Oxylabs](https://dashboard.oxylabs.io/) (1-week free trial available)



### Basic Usage

Via Smithery CLI:

- **Node.js** (v16+)

- `npx` command-line tool



Via uv:

- `uv` package manager – install it using [this guide](https://docs.astral.sh/uv/getting-started/installation/)



### Local/Dev Setup

- **Python 3.12+**

- `uv` package manager – install it using [this guide](https://docs.astral.sh/uv/getting-started/installation/)



---



## 🧩 API Parameters



The Oxylabs MCP Universal Scraper accepts these parameters:



| Parameter         | Description                                     | Values                    |

|-------------------|-------------------------------------------------|---------------------------|

| `url`             | The URL to scrape                               | Any valid URL             |

| `render`          | Use headless browser rendering                  | `html` or `None`          |

| `geo_location`    | Sets the proxy's geo location to retrieve data. | `Brasil`, `Canada`, etc.  |

| `user_agent_type` | Device type and browser                         | `desktop`, `tablet`, etc. |

| `output_format`   | The format of the output                        | `links`, `md`, `html`     |



---



## 🔧 Configuration



[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=oxylabs&config=eyJjb21tYW5kIjoidXZ4IG94eWxhYnMtbWNwIiwiZW52Ijp7Ik9YWUxBQlNfVVNFUk5BTUUiOiJPWFlMQUJTX1VTRVJOQU1FIiwiT1hZTEFCU19QQVNTV09SRCI6Ik9YWUxBQlNfUEFTU1dPUkQifX0%3D)



smithery



1. Go to https://smithery.ai/server/@oxylabs/oxylabs-mcp

2. Login with GitHub

3. Find the _Install_ section

4. Follow the instructions to generate the config



Auto install with Smithery CLI

```bash

# example for Claude Desktop

npx -y @smithery/cli@latest install @upstash/context7-mcp --client claude --key 

```



uvx



1. Install the uv

```bash

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

```



2. Use the following config

```json

{

  "mcpServers": {

    "oxylabs": {

      "command": "uvx",

      "args": ["oxylabs-mcp"],

      "env": {

        "OXYLABS_USERNAME": "OXYLABS_USERNAME",

        "OXYLABS_PASSWORD": "OXYLABS_PASSWORD"

      }

    }

  }

}

```



uv



1. Install the uvx 

```bash

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

```



2. Use the following config

```json

{

  "mcpServers": {

    "oxylabs": {

      "command": "uv",

      "args": [

        "--directory",

        "//oxylabs-mcp",

        "run",

        "oxylabs-mcp"

      ],

      "env": {

        "OXYLABS_USERNAME": "OXYLABS_USERNAME",

        "OXYLABS_PASSWORD": "OXYLABS_PASSWORD"

      }

    }

  }

}

```



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



---



## ⚙️ Environment variables



Oxylabs MCP server supports the following environment variables



| Name               | Description                                   | Mandatory           | Default |

|--------------------|-----------------------------------------------|---------------------|---------|

| `OXYLABS_USERNAME` | Your Oxylabs username                         | true                |         |

| `OXYLABS_PASSWORD` | Your Oxylabs password                         | true                |         |

| `LOG_LEVEL`        | Log level for the logs returned to the client | false               | `INFO`  |



---



## 📝 Logging



Server provides additional information about the tool calls in `notification/message` events



```json

{

  "method": "notifications/message",

  "params": {

    "level": "info",

    "data": "Create job with params: {\"url\": \"https://ip.oxylabs.io\"}"

  }

}

```



```json

{

  "method": "notifications/message",

  "params": {

    "level": "info",

    "data": "Job info: job_id=7333113830223918081 job_status=done"

  }

}

```



```json

{

  "method": "notifications/message",

  "params": {

    "level": "error",

    "data": "Error: request to Oxylabs API failed"

  }

}

```



---



## 🛡️ License



Distributed under the MIT License – see [LICENSE](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.



[![image](https://oxylabs.io/images/og-image.png)](https://oxylabs.io/)







  Made with ☕ by Oxylabs.  Feel free to give us a ⭐ if MCP saved you a weekend.