> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/integrations/web-scraper-api-integrations/model-context-protocol-mcp.md).

# Model Context Protocol (MCP)

The Oxylabs MCP server connects AI assistants ([Claude](https://claude.ai/), [Cursor](https://www.cursor.com/), and any other [Model Context Protocol](https://modelcontextprotocol.io/) client) to the real-world web.

Once connected, your assistant can scrape any URL (includes JavaScript rendering and geo-targeting), search the web, crawl sites, and extract structured data.

{% hint style="success" %}
**Open source & registry:** View the source code on [GitHub](https://github.com/oxylabs/oxylabs-mcp). The server is officially registered on the [MCP Registry](https://registry.modelcontextprotocol.io/) (`io.oxylabs/oxylabs-mcp`), [PyPI](https://pypi.org/project/oxylabs-mcp/), and [Smithery](https://smithery.ai/).
{% endhint %}

## Prerequisites

You need **at least one** credential set to unlock its corresponding tools. Providing both unlocks all tools listed below.

<table><thead><tr><th width="287">Credentials</th><th width="307">Where to get it</th><th width="165">Unlocks</th></tr></thead><tbody><tr><td>Web Scraper API <code>username</code> &#x26; <code>password</code></td><td><a href="https://dashboard.oxylabs.io/">Oxylabs dashboard</a> (free trial available)</td><td>Web Scraper API tools</td></tr><tr><td>AI Studio API key</td><td><a href="https://aistudio.oxylabs.io/settings/api-key">AI Studio Settings</a> (free credits included)</td><td>AI Studio tools</td></tr></tbody></table>

{% hint style="warning" %}
Only configure credentials you actually have. Placeholder values expose tools that will fail when called.
{% endhint %}

## Available tools

<table><thead><tr><th width="204">Tool</th><th width="428">What it does</th><th width="133">Requires</th></tr></thead><tbody><tr><td><code>universal_scraper</code></td><td>Scrapes any URL. Optional JavaScript rendering, geo-targeting, Markdown/HTML output</td><td>Web Scraper API</td></tr><tr><td><code>google_search_scraper</code></td><td>Google Search results, optionally parsed to structured JSON</td><td>Web Scraper API</td></tr><tr><td><code>amazon_search_scraper</code></td><td>Amazon search result pages, optionally parsed</td><td>Web Scraper API</td></tr><tr><td><code>amazon_product_scraper</code></td><td>Individual Amazon product pages</td><td>Web Scraper API</td></tr><tr><td><code>ai_scraper</code></td><td>AI-powered extraction from any URL (JSON, CSV, Markdown, TOON)</td><td>AI Studio</td></tr><tr><td><code>ai_crawler</code></td><td>Prompt-driven multi-page crawling and data collection </td><td>AI Studio</td></tr><tr><td><code>ai_browser_agent</code></td><td>Prompt-driven browser control: navigate, click, fill forms</td><td>AI Studio</td></tr><tr><td><code>ai_search</code></td><td>Web search with optional Markdown content of each result</td><td>AI Studio</td></tr><tr><td><code>ai_map</code></td><td>Maps website URLs</td><td>AI Studio</td></tr><tr><td><code>generate_schema</code></td><td>Generates custom extraction schemas for the AI Studio tools</td><td>AI Studio</td></tr></tbody></table>

## Choose how to connect

<table data-header-hidden><thead><tr><th width="117"></th><th>Hosted (recommended)</th><th>Local</th></tr></thead><tbody><tr><td></td><td><a href="#option-1-hosted-server-recommended"><strong>Hosted server</strong></a> (recommended)</td><td><a href="#option-2-run-the-server-locally"><strong>Local server</strong></a></td></tr><tr><td><strong>Install</strong></td><td>None</td><td><a href="https://docs.astral.sh/uv/">uv</a> + <code>uvx oxylabs-mcp</code></td></tr><tr><td><strong>Endpoint</strong></td><td><code>https://mcp.oxylabs.io/mcp</code></td><td>Cursor/Claude spawn the process</td></tr><tr><td><strong>Credentials</strong></td><td>HTTP headers</td><td>Environment variables</td></tr><tr><td><strong>Best for</strong></td><td>Quickest setup, no management</td><td>Offline control, local debugging, clients that cannot send custom headers</td></tr></tbody></table>

## Method 1: Hosted server (recommended)

Connect to Oxylabs hosted MCP server:

```
https://mcp.oxylabs.io/mcp
```

Pass credentials as request headers:

<table><thead><tr><th width="240">Credential</th><th>Header</th></tr></thead><tbody><tr><td>Web Scraper API</td><td><code>Authorization: Basic &#x3C;base64(username:password)></code></td></tr><tr><td>AI Studio</td><td><code>X-Oxylabs-AI-Studio-Api-Key: &#x3C;your API key></code></td></tr></tbody></table>

{% hint style="warning" %}
**Note:** Include only the headers for credentials you have.
{% endhint %}

### Claude Code

Install directly in the command line:

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

Omit a `--header` line if you do not have that credential.

### Claude Desktop

Claude Desktop built-in config editor uses local (`command`) servers. For the hosted endpoint, use Claude Code with the HTTP command above, or [run the server locally](#claude-desktop-2) and point Claude Desktop at that config.

### Cursor

1. Open **Cursor Settings** → **Customize** in the sidebar → **MCPs**
2. Click **+ New**
3. Choose **User** (all projects) or **Project** (workspace only)
4. Add the following to the opened `mcp.json`:<br>

   ```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"
         }
       }
     }
   }
   ```
5. Save, then confirm the server is enabled under **Customize → MCPs**.

{% hint style="info" %}
**Note:** *User* writes to `~/.cursor/mcp.json`. *Workspace* writes to `.cursor/mcp.json` in the chosen workspace. If both define the same server name, the *workspace* config takes priority.
{% endhint %}

## Method 2: Local server

The server is available on our [PyPI repository](https://pypi.org/project/oxylabs-mcp/).&#x20;

If not installed yet, install the [uv package](https://docs.astral.sh/uv/) according to the chosen operating system:

{% tabs %}
{% tab title="macOS / Linux" %}

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

{% endtab %}

{% tab title="Windows" %}

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

{% endtab %}
{% endtabs %}

Credentials are passed as environment variables (set **only** the ones you have):

| Variable                    | Description              |
| --------------------------- | ------------------------ |
| `OXYLABS_USERNAME`          | Web Scraper API username |
| `OXYLABS_PASSWORD`          | Web Scraper API password |
| `OXYLABS_AI_STUDIO_API_KEY` | AI Studio API key        |

### Claude Code

```bash
claude mcp add oxylabs -- command uvx args oxylabs-mcp \
  --env OXYLABS_USERNAME=YOUR_USERNAME \
  --env OXYLABS_PASSWORD=YOUR_PASSWORD \
  --env OXYLABS_AI_STUDIO_API_KEY=YOUR_API_KEY
```

{% hint style="info" %}
Manual config path for Claude Code: `~/.config/claude/mcp.json` (macOS/Linux) or `%USERPROFILE%\.config\claude\mcp.json` (Windows). The JSON shape matches Claude Desktop.
{% endhint %}

### Claude Desktop

1. Open **Claude → Settings → Developer → Edit Config**
2. Add the following to `claude_desktop_config.json`:<br>

   ```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"
         }
       }
     }
   }
   ```
3. Restart Claude Desktop

### Cursor

1. Open **Cursor Settings** → **Customize** in the sidebar → **MCPs**
2. Click **+ New**
3. Choose **User** (all projects) or **Project** (workspace only)
4. Add the following to the opened `mcp.json`:<br>

   ```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"
         }
       }
     }
   }
   ```
5. Save, then confirm the server is enabled under **Customize → MCPs**.

{% hint style="info" %}
**Note:** *User* writes to `~/.cursor/mcp.json`. *Workspaces* writes to `.cursor/mcp.json` in the chosen workspace. If both define the same server name, the *workspace* config takes priority.
{% endhint %}

## Verify the setup

After connecting, ask your assistant something that requires live web data (e.g. `“Scrape https://ip.oxylabs.io and return the content as Markdown.”`):

{% stepper %}
{% step %}
Confirm the `oxylabs` server appears and is enabled in your client’s MCP list.
{% endstep %}

{% step %}
Approve the tool call when prompted (clients ask before running MCP tools by default).
{% endstep %}

{% step %}
If the call fails, check credentials and client logs (Cursor: **Output → MCP Logs**).
{% endstep %}
{% endstepper %}

## Troubleshooting

<table><thead><tr><th width="251">Error</th><th>Solution</th></tr></thead><tbody><tr><td>Server missing from the client</td><td>Restart the app after editing config. Confirm JSON is valid.</td></tr><tr><td>Tools listed but calls fail</td><td>Placeholder credentials, wrong Base64, or missing header/env for that tool.</td></tr><tr><td>Hosted URL won’t connect</td><td>Client may not support custom headers, use local setup.</td></tr><tr><td><code>uvx</code> / command not found</td><td>Install <a href="https://docs.astral.sh/uv/">uv</a> and ensure it is on your <code>PATH</code>.</td></tr><tr><td>Cursor UI path looks different</td><td>Skip the UI and edit <code>mcp.json</code> directly (labels can change between Cursor versions).</td></tr></tbody></table>

{% hint style="success" %}
For issues or feature requests, open a GitHub issue or contact 24/7 Oxylabs support at [**support@oxylabs.io**](mailto:support@oxylabs.io).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/integrations/web-scraper-api-integrations/model-context-protocol-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.