> 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/cn/web-scraper-api-integrations/model-context-protocol-mcp.md).

# 模型上下文协议 (MCP)

使用 Oxylabs MCP 通过网页爬虫API 和 AI Studio 为 AI 助手提供实时网页抓取、搜索和提取工具。

Oxylabs MCP 服务器将 AI 助手（[Claude](https://claude.ai/), [Cursor](https://www.cursor.com/)，以及任何其他 [模型上下文协议](https://modelcontextprotocol.io/) 客户端）连接到真实世界的网络。

连接后，你的助手可以抓取任何 URL（包括 JavaScript 渲染和地理定位），搜索网页、爬取站点，并提取结构化数据。

{% hint style="success" %}
**开源与注册表：** 查看源代码于 [GitHub](https://github.com/oxylabs/oxylabs-mcp)。该服务器已正式注册到 [MCP Registry](https://registry.modelcontextprotocol.io/) (`io.oxylabs/oxylabs-mcp`), [PyPI](https://pypi.org/project/oxylabs-mcp/)，以及 [Smithery](https://smithery.ai/).
{% endhint %}

## 先决条件

你需要 **至少一组** 凭据来解锁其对应工具。提供两组即可解锁下面列出的所有工具。

<table><thead><tr><th width="287">凭据</th><th width="307">获取方式</th><th width="165">解锁</th></tr></thead><tbody><tr><td>网页爬虫API <code>username</code> &#x26; <code>password</code></td><td><a href="https://dashboard.oxylabs.io/">Oxylabs 控制面板</a> （可免费试用）</td><td>网页爬虫API 工具</td></tr><tr><td>AI Studio API 密钥</td><td><a href="https://aistudio.oxylabs.io/settings/api-key">AI Studio 设置</a> （包含免费额度）</td><td>AI Studio 工具</td></tr></tbody></table>

{% hint style="warning" %}
只配置你实际拥有的凭据。占位值会暴露出在调用时失败的工具。
{% endhint %}

## 可用工具

<table><thead><tr><th width="204">工具</th><th width="428">作用</th><th width="133">需要</th></tr></thead><tbody><tr><td><code>universal_scraper</code></td><td>抓取任何 URL。可选 JavaScript 渲染、地理定位、Markdown/HTML 输出</td><td>网页爬虫API</td></tr><tr><td><code>google_search_scraper</code></td><td>Google 搜索结果，可选择解析为结构化 JSON</td><td>网页爬虫API</td></tr><tr><td><code>amazon_search_scraper</code></td><td>Amazon 搜索结果页，可选择解析</td><td>网页爬虫API</td></tr><tr><td><code>amazon_product_scraper</code></td><td>单个 Amazon 商品页面</td><td>网页爬虫API</td></tr><tr><td><code>ai_scraper</code></td><td>基于 AI 的任意 URL 提取（JSON、CSV、Markdown、TOON）</td><td>AI Studio</td></tr><tr><td><code>ai_crawler</code></td><td>由提示驱动的多页面爬取和数据收集 </td><td>AI Studio</td></tr><tr><td><code>ai_browser_agent</code></td><td>由提示驱动的浏览器控制：导航、点击、填写表单</td><td>AI Studio</td></tr><tr><td><code>ai_search</code></td><td>网页搜索，可选包含每个结果的 Markdown 内容</td><td>AI Studio</td></tr><tr><td><code>ai_map</code></td><td>映射网站 URL</td><td>AI Studio</td></tr><tr><td><code>generate_schema</code></td><td>为 AI Studio 工具生成自定义提取 schema</td><td>AI Studio</td></tr></tbody></table>

## 选择连接方式

<table data-header-hidden><thead><tr><th width="117"></th><th>托管（推荐）</th><th>本地</th></tr></thead><tbody><tr><td></td><td><a href="#option-1-hosted-server-recommended"><strong>托管服务器</strong></a> （推荐）</td><td><a href="#option-2-run-the-server-locally"><strong>本地服务器</strong></a></td></tr><tr><td><strong>安装</strong></td><td>无</td><td><a href="https://docs.astral.sh/uv/">uv</a> + <code>uvx oxylabs-mcp</code></td></tr><tr><td><strong>端点</strong></td><td><code>https://mcp.oxylabs.io/mcp</code></td><td>Cursor/Claude 启动该进程</td></tr><tr><td><strong>凭据</strong></td><td>HTTP 标头</td><td>环境变量</td></tr><tr><td><strong>最适合</strong></td><td>最快设置，无需管理</td><td>离线控制、本地调试、无法发送自定义标头的客户端</td></tr></tbody></table>

## 方法 1：托管服务器（推荐）

连接到 Oxylabs 托管的 MCP 服务器：

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

将凭据作为请求标头传递：

<table><thead><tr><th width="240">凭据</th><th>标头</th></tr></thead><tbody><tr><td>网页爬虫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" %}
**注意：** 只包含你拥有的凭据对应的标头。
{% endhint %}

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

如果你没有该凭据，则省略一个 `--header` 行。

### Claude Desktop

Claude Desktop 内置配置编辑器使用本地（`命令`）服务器。对于托管端点，请使用上面的 HTTP 命令通过 Claude Code，或者 [本地运行服务器](#claude-desktop-2) 并让 Claude Desktop 指向该配置。

### Cursor

1. 打开 **Cursor 设置** → **自定义** 在侧边栏中 → **MCPs**
2. 点击 **+ 新建**
3. 选择 **用户** （所有项目）或 **项目** （仅工作区）
4. 将以下内容添加到打开的 `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. 保存，然后确认服务器已在 **自定义 → MCPs**.

{% hint style="info" %}
**注意：** *用户* 写入到 `~/.cursor/mcp.json`. *工作区* 写入到 `.cursor/mcp.json` 在所选工作区中。如果两者定义了相同的服务器名称， *工作区* 配置优先。
{% endhint %}

## 方法 2：本地服务器

该服务器可在我们的 [PyPI 仓库](https://pypi.org/project/oxylabs-mcp/).&#x20;

如果尚未安装，请根据所选操作系统安装 [uv 包](https://docs.astral.sh/uv/) ：

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

凭据作为环境变量传递（仅设置 **你拥有的** 那些）：

| 变量                          | 描述               |
| --------------------------- | ---------------- |
| `OXYLABS_USERNAME`          | 网页爬虫API 用户名      |
| `OXYLABS_PASSWORD`          | 网页爬虫API 密码       |
| `OXYLABS_AI_STUDIO_API_KEY` | AI Studio API 密钥 |

### 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" %}
Claude Code 的手动配置路径： `~/.config/claude/mcp.json` （macOS/Linux）或 `%USERPROFILE%\.config\claude\mcp.json` （Windows）。JSON 结构与 Claude Desktop 相同。
{% endhint %}

### Claude Desktop

1. 打开 **Claude → 设置 → 开发者 → 编辑配置**
2. 将以下内容添加到 `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. 重启 Claude Desktop

### Cursor

1. 打开 **Cursor 设置** → **自定义** 在侧边栏中 → **MCPs**
2. 点击 **+ 新建**
3. 选择 **用户** （所有项目）或 **项目** （仅工作区）
4. 将以下内容添加到打开的 `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. 保存，然后确认服务器已在 **自定义 → MCPs**.

{% hint style="info" %}
**注意：** *用户* 写入到 `~/.cursor/mcp.json`. *工作区* 写入到 `.cursor/mcp.json` 在所选工作区中。如果两者定义了相同的服务器名称， *工作区* 配置优先。
{% endhint %}

## 验证设置

连接后，让你的助手处理一个需要实时网页数据的问题（例如 `“抓取 https://ip.oxylabs.io 并将内容以 Markdown 返回。”`):

{% stepper %}
{% step %}
确认 `oxylabs` 服务器出现在客户端的 MCP 列表中并已启用。
{% endstep %}

{% step %}
在提示时批准工具调用（默认情况下，客户端在运行 MCP 工具前会询问）。
{% endstep %}

{% step %}
如果调用失败，请检查凭据和客户端日志（Cursor： **输出 → MCP 日志**).
{% endstep %}
{% endstepper %}

## 故障排除

<table><thead><tr><th width="251">错误</th><th>解决方案</th></tr></thead><tbody><tr><td>客户端中缺少服务器</td><td>编辑配置后重启应用。确认 JSON 有效。</td></tr><tr><td>列出的工具但调用失败</td><td>占位凭据、错误的 Base64，或该工具缺少 header/env。</td></tr><tr><td>托管 URL 无法连接</td><td>客户端可能不支持自定义标头，请使用本地设置。</td></tr><tr><td><code>uvx</code> 命令未找到</td><td>安装 <a href="https://docs.astral.sh/uv/">uv</a> 并确保它已在你的 <code>PATH</code>.</td></tr><tr><td>Cursor 界面路径看起来不同</td><td>跳过 UI 并直接编辑 <code>mcp.json</code> （标签在 Cursor 版本之间可能会变化）。</td></tr></tbody></table>

{% hint style="success" %}
如有问题或功能请求，请提交 GitHub issue，或联系 24/7 Oxylabs 支持，地址为 [**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/cn/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.