io.oxylabs/oxylabs-mcp
Fetch and process content from specified URLs & sources using the Oxylabs Web Scraper API.
Open source Repository Open in the app JSON README (API)
About
Fetch and process content from specified URLs & sources using the Oxylabs Web Scraper API.
Details
- Kind
- MCP servers
- Topic
- Web search, scraping & browser
- Publisher
- io.oxylabs
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.9.1
- Stars
- 104
- Forks
- 25
- Last push
- 2026-08-26T08:41:46Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:45
- Updated
- 2026-08-29 04:01:45
- Origin id
io.oxylabs/oxylabs-mcp
README
<p align="center">
<img src="https://storage.googleapis.com/oxylabs-public-assets/oxylabs_mcp.svg" alt="Oxylabs + MCP">
</p>
<h1 align="center" style="border-bottom: none;">
Oxylabs MCP Server
</h1>
<p align="center">
<em>The missing link between AI models and the real‑world web: one API that delivers clean, structured data from any site.</em>
</p>
<div align="center">
[](https://pypi.org/project/oxylabs-mcp/)
[](https://discord.gg/Pds3gBmKMH)
[](LICENSE)
[](https://mseep.ai/app/f6a9c0bc-83a6-4f78-89d9-f2cec4ece98d)
<br/>
<a href="https://glama.ai/mcp/servers/@oxylabs/oxylabs-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@oxylabs/oxylabs-mcp/badge" alt="Oxylabs Server MCP server" />
</a>
</div>
---
## 📖 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)](https://modelcontextprotocol.io/), the open standard for connecting AI assistants to external tools and data.
## 🛠️ MCP Tools
Oxylabs MCP provides two sets of tools that can be used together or independently:
### Oxylabs Web Scraper API tools
1. **universal_scraper**: scrapes any URL, with optional JavaScript rendering, geo-targeting, and Markdown/HTML/links output;
2. **google_search_scraper**: extracts results from Google Search, with optional parsing into structured JSON;
3. **amazon_search_scraper**: scrapes Amazon search result pages, with optional parsing into structured JSON;
4. **amazon_product_scraper**: extracts data from individual Amazon product pages.
### Oxylabs AI Studio tools
5. **ai_scraper**: scrapes content from any URL with AI-powered extraction, in JSON, CSV, Markdown, or TOON format;
6. **ai_crawler**: crawls a website from a starting URL based on a prompt and collects data across multiple pages;
7. **ai_browser_agent**: controls a real browser based on a prompt — navigates, clicks, fills forms — and returns the result;
8. **ai_search**: searches the web and optionally returns Markdown content of each result;
9. **ai_map**: maps a website's URLs, filtered by keywords or a prompt;
10. **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 your username and password from [Oxylabs](https://dashboard.oxylabs.io/) (1-week free trial available);
- **Oxylabs AI Studio API key**: obtain your API key from [Oxylabs AI Studio](https://aistudio.oxylabs.io/settings/api-key) (1000 credits free).
To run the server locally (Option 2 below) you will also need the [uv](https://docs.astral.sh/uv/) package manager:
```bash
# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```powershell
# 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:
| Credential | Header |
|--------------------------------|------------------------------------------------------------------|
| Web Scraper API | `Authorization: Basic <base64(username:password)>` |
| Web Scraper API (alternative) | `X-Oxylabs-Username` and `X-Oxylabs-Password` |
| AI Studio | `X-Oxylabs-AI-Studio-Api-Key` |
Setup with **Claude Code**:
```bash
claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
--header "Authorization: Basic $(echo -n 'YOUR_USERNAME:YOUR_PASSWORD' | base64)" \
--header "X-Oxylabs-AI-Studio-Api-Key: YOUR_API_KEY"
```
Setup with **Cursor** or any client that supports remote MCP servers with custom headers:
```json
{
"mcpServers": {
"oxylabs": {
"url": "https://mcp.oxylabs.io/mcp",
"headers": {
"Authorization": "Basic <base64 of username:password>",
"X-Oxylabs-AI-Studio-Api-Key": "YOUR_API_KEY"
}
}
}
}
```
The server is also listed on [Smithery](https://smithery.ai/servers/oxylabsmcp/oxylabs-mcp).
> **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 |
|-----------------------------|-----------------------------------------------|---------|
| `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 the provided credentials, the server automatically exposes the corresponding tools:
- If only `OXYLABS_USERNAME` and `OXYLABS_PASSWORD` are provided, the server exposes the Web Scraper API tools;
- If only `OXYLABS_AI_STUDIO_API_KEY` is provided, the server exposes the AI Studio tools;
- If all three are provided, the server exposes all tools.
❗ **Important: only set the environment variables you have real credentials for.
Leaving placeholder values will result in exposed tools that do not work.**
#### Configure with uvx
Installs the [package from PyPI](https://pypi.org/project/oxylabs-mcp/) and runs it automatically:
```json
{
"mcpServers": {
"oxylabs": {
"command": "uvx",
"args": ["oxylabs-mcp"],
"env": {
"OXYLABS_USERNAME": "YOUR_USERNAME",
"OXYLABS_PASSWORD": "YOUR_PASSWORD",
"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:
```json
{
"mcpServers": {
"oxylabs": {
"command": "uv",
"args": [
"--directory",
"/<absolute-path-to-folder>/oxylabs-mcp",
"run",
"oxylabs-mcp"
],
"env": {
"OXYLABS_USERNAME": "YOUR_USERNAME",
"OXYLABS_PASSWORD": "YOUR_PASSWORD",
"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:
```bash
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:
| Credential | How to pass it |
|---------------------------|--------------------------------------------------------------------------------------------------------|
| Web Scraper API | `Authorization: Basic <base64(username:password)>` (standard HTTP Basic auth) |
| Web Scraper API (alternative) | `X-Oxylabs-Username` and `X-Oxylabs-Password` headers |
| AI Studio | `X-Oxylabs-AI-Studio-Api-Key` header |
Example client configuration:
```json
{
"mcpServers": {
"oxylabs": {
"url": "https://your-host:8000/mcp",
"headers": {
"Authorization": "Basic <base64 of username:password>",
"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:
```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"
}
}
```
## ✨ Key Features
<details>
<summary><strong> Scrape content from any site</strong></summary>
<br>
- 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
</details>
<details>
<summary><strong> Automatically get AI-ready data</strong></summary>
<br>
- Automatically clean and convert HTML to Markdown for improved readability
- Use automated parsers for popular targets like Google, Amazon, and more
</details>
<details>
<summary><strong> Manage CAPTCHA & geo-restrictions</strong></summary>
<br>
- 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
</details>
<details>
<summary><strong> Flexible setup & cross-platform support</strong></summary>
<br>
- Set rendering and parsing options if needed
- Feed data directly into AI models or analytics tools
- Works on macOS, Windows, and Linux
</details>
<details>
<summary><strong> Built-in error handling and request management</strong></summary>
<br>
- Comprehensive error handling and reporting
- Smart rate limiting and request management
</details>
## 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](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.
[](https://oxylabs.io/)
<div align="center">
<sub>
Made with ☕ by <a href="https://oxylabs.io">Oxylabs</a>. Feel free to give us a ⭐ if MCP saved you a weekend.
</sub>
</div>
mcp-name: io.oxylabs/oxylabs-mcp
## Solutions made based on this MCP:
[Michelin Detour](https://michelindetour.com/)