> 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/products/web-scraper-api/solutions-for-ai-workflows/model-context-protocol-mcp.md).

# Model Context Protocol (MCP)

The **Model Context Protocol (MCP)** integration with [**Oxylabs' Web Scraper API**](https://oxylabs.io/products/scraper-api/web) enables the delivery of structured, AI-ready data optimized for large language model (LLM) workflows.

MCP ensures that context, metadata, and instructions are correctly formatted, allowing LLMs, such as Anthropic’s Claude to interpret and utilize the data effectively.

You can easily use Web Scraper API MCP integration with:

* [**Claude Desktop**](#setup-with-claude-desktop)
* [**Claude Code**](#claude-code-cli-setup)
* [**Cursor**](#running-on-cursor)

{% hint style="success" %}
Visit the Oxylabs GitHub repository for a complete working example of [MCP integration with the Web Scraper API](https://github.com/oxylabs/oxylabs-mcp).
{% endhint %}

## Setup with Claude Desktop

{% hint style="warning" %}
Before you start, make sure you have [**Claude Desktop**](https://claude.ai/download) installed. 
{% endhint %}

### Using Smithery.ai

Install [**Node.js and the npm**](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) command line interface. If you already have them installed, run the following command to update npm to the latest version:

```
npm install -g npm
```

To install Oxylabs MCP server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@oxylabs/oxylabs-mcp), run this command:

```
npx -y @smithery/cli install @oxylabs/oxylabs-mcp --client claude
```

During the installation process, you’ll be prompted to enter your API user username and password. Enter these credentials when requested.

Once the installation is complete, open Claude Desktop and configure the scraper to start using MCP-enhanced outputs.

### Using UV

Install [**uv**](https://docs.astral.sh/uv/getting-started/installation/), as an alternative to npm. Refer to the [**Model Context Protocol Quickstart Guide**](https://modelcontextprotocol.io/quickstart/user) to understand the configuration process.

To integrate the MCP server with **Claude Desktop**, update the `claude_desktop_config.json` file as follows:

```json
{
  "mcpServers": {
    "oxylabs_mcp": {
      "command": "uvx",
      "args": ["oxylabs-mcp"],
      "env": {
        "OXYLABS_USERNAME": "your_username",
        "OXYLABS_PASSWORD": "your_password"
      }
    }
  }
}
```

Replace `your_username` and `your_password` with your API user username and password.

Save the changes to the configuration file and restart Claude Desktop to ensure the updated settings take effect.

## Claude Code CLI setup

{% hint style="warning" %}
Before you start, make sure you have [**Claude Code**](https://docs.anthropic.com/en/docs/claude-code) installed.
{% endhint %}

Claude Code has a built-in command to add MCP servers directly from the terminal. Depending on your preferred package manager, follow one of the setup methods below.

### Using UV (recommended)

Install [**uv**](https://docs.astral.sh/uv/getting-started/installation/) if you haven't already. Then run the following command in your terminal to add the Oxylabs MCP server to Claude Code:

```bash
claude mcp add oxylabs -- command uvx args oxylabs-mcp --env OXYLABS_USERNAME=your_username --env OXYLABS_PASSWORD=your_password
```

Replace `your_username` and `your_password` with your API user username and password.

### Using NPM / NPX

Install [**Node.js and npm**](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) if you haven't already. If `npm` is already installed, make sure it's up to date:

```bash
npm install -g npm
```

Then run the following command in your terminal to add the Oxylabs MCP server to Claude Code:

```bash
claude mcp add oxylabs -- command npx args -y @oxylabs/oxylabs-mcp --env OXYLABS_USERNAME=your_username --env OXYLABS_PASSWORD=your_password
```

Replace `your_username` and `your_password` with your API user username and password.

{% hint style="info" %}
**Note:** If you prefer to edit files manually, Claude Code looks for its configuration file at `~/.config/claude/mcp.json` (on Mac/Linux) or `%USERPROFILE%.config\claude\mcp.json` (on Windows). The JSON structure inside that file matches the exact format used for Claude Desktop.
{% endhint %}

## Running on Cursor

Configuring Cursor Note: Requires Cursor version 0.46+

To configure Oxylabs in Cursor:<br>

1. Select Cursor → Settings → Cursor Settings → MCP Tools
2. Click "Add Custom MCP"
3. Add the following configuration:

```
{
  "mcpServers": {
    "oxylabs": {
      "command": "uvx",
      "args": ["oxylabs-mcp"],
      "env": {
        "OXYLABS_USERNAME": "your_username",
        "OXYLABS_PASSWORD": "your_password",
        "OXYLABS_AI_STUDIO_API_KEY": "your_ai_studio_api_key"
      }
    }
  }
}
```

Replace `your_username` and `your_password` with your API user username and password. Also replace `your_ai_studio_api_key` with your Oxylabs AI Studio API key.

After adding the configuration, 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.


---

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

```
GET https://developers.oxylabs.io/products/web-scraper-api/solutions-for-ai-workflows/model-context-protocol-mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.