> 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/ai-workflows/mcp.md).

# Model Context Protocol (MCP)

Use Oxylabs MCP to give AI assistants live web scraping, search, and extraction tools via Oxylabs products.

Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data. With Oxylabs MCP integrations, assistants such as [Claude](https://claude.ai/) and [Cursor](https://www.cursor.com/) can access live web data – scrape pages, search the web, crawl sites, and control remote browsers.

Oxylabs offers MCP integrations for three products:

<table><thead><tr><th width="211">Product</th><th>MCP server</th><th>Setup</th></tr></thead><tbody><tr><td><a href="#web-api">Web API</a></td><td><code>oxylabs-web-api-mcp</code></td><td>Hosted or local</td></tr><tr><td><a href="#headless-browser">Agent Browser</a></td><td><code>hb.oxylabs.io</code></td><td>Local, via Playwright MCP</td></tr><tr><td><a href="#web-scraper-api">Web Scraper API</a></td><td><code>mcp.oxylabs.io</code></td><td>Local or self-hosted</td></tr></tbody></table>

{% hint style="info" %}
**Note:** Each product has its own MCP server and credentials. Set up only the ones you need – they can also be combined.
{% endhint %}

## Web API

Connect Web API through its self-hosted MCP server `oxylabs-web-api-mcp`, to search the web, read pages as Markdown, extract fields as JSON, and call dedicated scrapers.

### Prerequisites

•       Web API key:  From the Web API instance and generate an API key from the [dashboard](https://dashboard.oxylabs.io/).

•       [**`uv`**](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10 or higher.

### Available tools

<table><thead><tr><th width="188.30078125">Tool</th><th>Does</th></tr></thead><tbody><tr><td><code>search</code></td><td>Search the live web – <code>query</code>, <code>max_results</code>, <code>location</code></td></tr><tr><td><code>scrape</code></td><td>Read one URL, Markdown by default – <code>url</code>, <code>format</code>, <code>location</code>, <code>device</code>, <code>run_js</code></td></tr><tr><td><code>extract</code></td><td>Named fields off a page as JSON – <code>url</code>, <code>prompt</code>, <code>location</code>, <code>run_js</code></td></tr><tr><td><code>check_scrape</code></td><td>Collect a JavaScript-rendering job – <code>job_id</code></td></tr><tr><td><code>read_scraped</code></td><td>Read a large page that was offloaded to disk, in chunks</td></tr><tr><td><code>list_scrapers</code></td><td>List implemented scrape endpoints, or describe one – <code>endpoint</code></td></tr><tr><td><code>scrape_target</code></td><td>Call a target-specific endpoint – <code>endpoint</code>, <code>params</code></td></tr></tbody></table>

### Installation

```bash
uv tool install git+https://github.com/oxylabs/web-api-mcp
```

Then point your client at the `oxylabs/web-api-mcp` binary.&#x20;

<details>

<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add oxylabs-web-api -- oxylabs-web-api-mcp
```

</details>

<details>

<summary><strong>Claude Desktop or Cursor</strong></summary>

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "command": "oxylabs-web-api-mcp",
      "env": { "OXYLABS_WEB_API_KEY": "your_api_key_here" }
    }
  }
}
```

</details>

Claude Code can instead take the [skills](https://github.com/oxylabs/web-api-skills) repository as a plugin, which wires this server and the skills together:

```bash
/plugin marketplace add oxylabs/web-api-skills
/plugin install oxylabs-web-api
```

#### Self-hosted server (HTTP)

Run one shared server for a team, or for agents that can't start local processes:

```bash
export OXYLABS_WEB_API_KEY=WEB_API_KEY
export MCP_ALLOWED_HOSTS='mcp.internal.example.com,localhost:*'
oxylabs-web-api-mcp --transport http --host 0.0.0.0 --port 8080
```

{% hint style="warning" %}
**Important:** `MCP_ALLOWED_HOSTS` is required – list the hostname clients connect to, or every request is rejected with `421 Misdirected Request`. The server has no authentication of its own, so anyone who can reach it spends its key: keep it behind a VPN or an authenticated ingress, never on the public internet.
{% endhint %}

The endpoint is `http://<host>:8080/mcp`. Callers can send their own key in an `Authorization`: Bearer header; otherwise, the server uses `OXYLABS_WEB_API_KEY`. A `Dockerfile` is also available in the [repository](https://github.com/oxylabs/web-api-mcp).

### Configuration

<table><thead><tr><th width="231.22265625">Variable</th><th width="413.6328125">Description</th><th>Default value</th></tr></thead><tbody><tr><td><code>OXYLABS_RATE_LIMIT</code></td><td>Caps the server's spend, e.g. <code>100/1h</code>.</td><td>Off</td></tr><tr><td><code>OXYLABS_EXTRACT_APPROVAL</code></td><td>Set to <code>0</code> to skip the approval prompt for structured extraction.</td><td>1</td></tr><tr><td><code>OXYLABS_MAX_INLINE_TOKENS</code></td><td>Pages above this size are saved to disk (local) or truncated (<code>HTTP</code>).</td><td>10000</td></tr><tr><td><code>OXYLABS_TIMEOUT</code></td><td>Request timeout, in seconds.</td><td>120</td></tr><tr><td><code>OXYLABS_RETRIES</code></td><td>Retries on temporary errors (<code>429</code>, <code>500</code>, <code>502</code>, <code>503</code>, <code>504</code>).</td><td>2</td></tr></tbody></table>

## Agent Browser

By integrating Oxylabs Agent Browser with MCP, you can implement AI systems to perform **web navigation, data retrieval, and automation** tasks using remote browsers at `hb.oxylabs.io` with advanced autonomous navigation capabilities and [**Residential Proxy**](https://oxylabs.io/products/residential-proxy-pool) integration.

The MCP host (such as [**Claude Desktop**](https://claude.ai/download) or [**Cursor**](https://www.cursor.com/)) comes with a built-in MCP client. **Playwright-MCP** acts as an MCP server, and instead of using a local browser, it connects to Agent Browser via a secure WebSocket connection (WSS).

<figure><img src="https://1851335073-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYs6miJGSyByWb3MsE9vk%2Fuploads%2FDcKLNjxqQmpmYr5YmvV4%2Fimage.png?alt=media&amp;token=69b1b2cb-527c-44a8-ae49-9c5348df1b56" alt=""><figcaption></figcaption></figure>

### Prerequisites

•       Agent Browser username and password from the [Oxylabs dashboard](https://dashboard.oxylabs.io/).

•       [Node.js](https://nodejs.org/) 18.0.0 or higher (includes `npx`).

### Installation

Connect to the MCP server via Claude Desktop / Cursor or via Claude Code. The setup code is given below.

<details>

<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add oxylabs_headless_browser \
  -- npx @playwright/mcp@latest --cdp-endpoint wss://USERNAME:PASSWORD@hb.oxylabs.io
```

</details>

<details>

<summary><strong>Claude Desktop or Cursor</strong></summary>

```json
{
  "mcpServers": {
    "oxylabs_headless_browser": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint",
        "wss://USERNAME:PASSWORD@hb.oxylabs.io"
      ]
    }
  }
}

```

</details>

#### Country selection

You can specify a country for your browser session by adding the `?p_cc` parameter to your connection URL:

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://USERNAME:PASSWORD@hb.oxylabs.io?p_cc=US"
  ]
}
```

To choose the browser's location options, visit the [Geolocation & Proxy Selection](/products/agent-browser/geolocation-and-proxy-selection.md) page. If you don't specify a location, one is assigned automatically based on availability.

## Web Scraper API

Connect Web Scraper API through the Oxylabs MCP server at `mcp.oxylabs.io` to scrape any URL, Google Search, and Amazon.

{% hint style="info" %}
The MCP server is also available on the [MCP Registry](https://registry.modelcontextprotocol.io/) (`io.oxylabs/oxylabs-mcp`), [PyPI](https://pypi.org/project/oxylabs-mcp/), and [Smithery](https://smithery.ai/servers/oxylabsmcp/oxylabs-mcp).
{% endhint %}

### Prerequisites

* Web Scraper API `USERNAME` and `PASSWORD` from the [Oxylabs dashboard](https://dashboard.oxylabs.io/).
* For the local method only: [**`uv`**](https://docs.astral.sh/uv/getting-started/installation/)&#x20;

### Available tools

<table><thead><tr><th width="249.4765625">Tool</th><th>Description</th></tr></thead><tbody><tr><td><code>universal_scraper</code></td><td>Scrapes any URL, with optional JavaScript rendering, geo-targeting, and Markdown/HTML/links output.</td></tr><tr><td><code>google_search_scraper</code></td><td>Scrapes Google Search results, optionally parsed into structured JSON.</td></tr><tr><td><code>amazon_search_scraper</code></td><td>Scrapes Amazon search result pages, optionally parsed into structured JSON.</td></tr><tr><td><code>amazon_product_scraper</code></td><td>Scrapes individual Amazon product pages.</td></tr></tbody></table>

### Installation

There are two ways to use the server: connect to the [**hosted instance**](#method-1-hosted-server-no-installation) (no installation) or [**run it locally**](#method-2-local-server) with credentials in environment variables.

#### Method  1: Hosted server (no installation)

Connect to Oxylabs hosted MCP server:

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

Pass credentials as request headers:

```shellscript
Authorization: Basic <base64(username:password)>
```

<details>

<summary><strong>Claude Code</strong></summary>

Install directly in the command line:

```shellscript
claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  --header "Authorization: Basic $(echo -n 'YOUR_USERNAME:YOUR_PASSWORD' | base64)" \
```

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

</details>

<details>

<summary><strong>Cursor</strong></summary>

Install directly in the command line:

```shellscript
claude mcp add --transport http oxylabs https://mcp.oxylabs.io/mcp \
  --header "Authorization: Basic $(echo -n 'YOUR_USERNAME:YOUR_PASSWORD' | base64)" \
```

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

</details>

#### Method  2: Local server

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

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

```bash
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):

<table><thead><tr><th width="289.98828125">Variable</th><th>Description</th></tr></thead><tbody><tr><td><code>OXYLABS_USERNAME</code></td><td>Web Scraper API username</td></tr><tr><td><code>OXYLABS_PASSWORD</code></td><td>Web Scraper API password</td></tr></tbody></table>

<details>

<summary><strong>Claude Code</strong></summary>

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

{% 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 %}

</details>

<details>

<summary><strong>Claude Desktop or Cursor</strong></summary>

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

</details>

### Advanced options

* **Self-hosted server:** run `MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8000 uvx oxylabs-mcp`. Clients connect to `https://your-host:8000/mcp` and send credentials as headers, the same way as with the hosted server.
* **Alternative headers:** on the hosted or self-hosted server, you can send `X-Oxylabs-Username` and `X-Oxylabs-Password` instead of `Authorization: Basic`.
* **Logging:** set `LOG_LEVEL` to control the logs returned to the client. The default is `INFO`.

## Use multiple products together

You can run all three servers in the same client. Combine their entries under one `mcpServers` object.

<details>

<summary>Example</summary>

```json
{
  "mcpServers": {
    "oxylabs": {
      "command": "uvx",
      "args": ["oxylabs-mcp"],
      "env": {
        "OXYLABS_USERNAME": "WEB_SCRAPER_API_USERNAME",
        "OXYLABS_PASSWORD": "WEB_SCRAPER_API_PASSWORD"
      }
    },
    "oxylabs-web-api": {
      "command": "oxylabs-web-api-mcp",
      "env": {
        "OXYLABS_WEB_API_KEY": "WEB_API_KEY"
      }
    },
    "oxylabs_headless_browser": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--cdp-endpoint",
        "wss://HB_USERNAME:HB_PASSWORD@hb.oxylabs.io"
      ]
    }
  }
}

```

</details>

## Verify the setup

1. Check that your servers appear as enabled in your client's MCP list (in Claude Code, run `/mcp`).
2. Send a test prompt for each product you set up, and approve the tool call if prompted.

## Troubleshooting

<table><thead><tr><th width="341.37109375">Issue</th><th>Solution</th></tr></thead><tbody><tr><td>Server doesn't appear in the client</td><td>Make sure the JSON is valid, then restart the app.</td></tr><tr><td>Tools appear, but calls fail</td><td>Check for placeholder credentials, an incorrect Base64 value, or credentials from the wrong product.</td></tr><tr><td>Hosted server won't connect</td><td>Your client may not support custom headers. Use the local method.</td></tr><tr><td><code>uvx</code>, <code>npx</code>, or <code>oxylabs-web-api-mcp</code>: command not found</td><td>Install <code>uv</code> or Node.js 18.0.0+ (and the Web API server, if needed) and make sure it's on your <code>PATH</code>.</td></tr><tr><td>Agent Browser won't connect</td><td>Verify your credentials and make sure your firewall isn't interfering with WebSocket connections.</td></tr><tr><td>Cursor menus look different</td><td>Edit <code>mcp.json</code> directly – menu labels can change between Cursor versions. Check logs in <strong>Output → MCP Logs</strong>.</td></tr></tbody></table>

## Resources

* [Web API MCP GitHub repository](https://github.com/oxylabs/web-api-mcp)&#x20;
* [Agent Browser GitHub repository](https://github.com/oxylabs/oxylabs-hb-mcp)
* [Web Scraper API GitHub repository](https://github.com/oxylabs/oxylabs-mcp)&#x20;


---

# 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/ai-workflows/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.