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

# 模型上下文协议 (MCP)

使用 Oxylabs MCP，通过 Oxylabs 产品为 AI 助手提供实时网页爬取、搜索和提取工具。

模型上下文协议（MCP）是一种用于将 AI 助手连接到外部工具和数据的开放标准。通过 Oxylabs MCP 集成，诸如 [Claude](https://claude.ai/) 和 [Cursor](https://www.cursor.com/) 可以访问实时网页数据——抓取页面、搜索网络、爬取网站，以及控制远程浏览器。

Oxylabs 为两个产品提供 MCP 集成：

<table><thead><tr><th width="136">产品</th><th width="183">MCP 服务器</th><th>设置</th></tr></thead><tbody><tr><td><a href="#web-api">Web API</a></td><td><code>oxylabs-web-api-mcp</code></td><td>远程（由 Oxylabs 托管）或自托管（由你运行）</td></tr><tr><td><a href="#agent-browser">Agent Browser</a></td><td><code>hb-mcp</code></td><td>自托管</td></tr></tbody></table>

{% hint style="info" %}
**注意：** 每个产品都有各自的 MCP 服务器和凭据。只设置你需要的部分——它们也可以组合使用。
{% endhint %}

## Web API

将 Web API 连接到你的 AI 代理，以搜索网络、按你选择的格式抓取页面、将字段提取为 JSON，并调用专用爬虫——全部通过一个 MCP 连接完成。你可以在以下位置找到所有详细信息： [Web API MCP GitHub 仓库](https://github.com/oxylabs/web-api-mcp).

你可以通过两种方式连接：

* [**远程 MCP**](#option-1-remote-mcp) ——连接到由 Oxylabs 托管并维护的服务器。无需安装或更新。
* [**自托管 MCP**](#option-2-self-hosted-mcp) ——在你自己的环境中部署并管理服务器，以获得更多控制权。

<table><thead><tr><th width="160"></th><th width="288">远程 MCP</th><th>自托管 MCP</th></tr></thead><tbody><tr><td><strong>服务器运行于</strong></td><td>Oxylabs 基础设施</td><td>你的机器或基础设施</td></tr><tr><td><strong>设置</strong></td><td>将服务器 URL 和你的 API 密钥添加到客户端</td><td>安装 <code>uv</code>、Python 和服务器，然后配置你的客户端</td></tr><tr><td><strong>更新和维护</strong></td><td>由 Oxylabs 管理</td><td>由你管理</td></tr><tr><td><strong>服务器设置</strong></td><td>由 Oxylabs 管理</td><td>可通过环境变量配置</td></tr><tr><td><strong>最适合</strong></td><td>让兼容的代理快速访问 Web API 的最快方式</td><td>对环境拥有完全控制，或无法使用自定义请求头连接远程服务器的客户端</td></tr></tbody></table>

### 要求

* **Web API 密钥：** 在 [Oxylabs 仪表板](https://dashboard.oxylabs.io/)中，创建一个 Web API 产品实例，打开它，并复制实例页面顶部显示的 API 密钥。
* **对于远程 MCP：** 支持带自定义请求头的远程（HTTP）MCP 服务器的 MCP 客户端，例如 Claude Code、Codex、Cursor 等。
* **对于自托管 MCP：** [**`uv`**](https://docs.astral.sh/uv/getting-started/installation/) 以及 Python 3.10 或更高版本。

### 可用工具

<table><thead><tr><th width="188.30078125">工具</th><th>作用</th></tr></thead><tbody><tr><td><code>search</code></td><td>搜索实时网页—— <code>query</code>, <code>max_results</code>, <code>location</code></td></tr><tr><td><code>scrape</code></td><td>读取一个 URL，默认以 Markdown 返回，或返回命名字段为 JSON—— <code>url</code>, <code>format</code>, <code>location</code>, <code>device</code>, <code>run_js</code>, <code>json_prompt</code>, <code>json_schema</code></td></tr><tr><td><code>scrape_target</code></td><td>调用特定目标的爬虫—— <code>endpoint</code>, <code>params</code>, <code>structured</code>, <code>parser</code>, <code>json_prompt</code>, <code>json_schema</code></td></tr><tr><td><code>list_scrapers</code></td><td>列出可用的抓取端点，或描述其中一个—— <code>endpoint</code></td></tr><tr><td><code>check_scrape</code></td><td>收集排队中的任务，例如需要渲染 JavaScript 的抓取—— <code>request_id</code></td></tr><tr><td><code>read_scraped</code></td><td>分块读取已卸载到磁盘的大页面——仅在服务器本地运行（stdio）时可用</td></tr></tbody></table>

{% hint style="info" %}
**注意：** 所有工具均为只读，因此许多客户端可以直接运行，无需请求批准。
{% endhint %}

### 选项 1：远程 MCP

将你的客户端连接到 Oxylabs 托管的服务器：

```
https://mcp.oxylabs.io/web-api-mcp
```

服务器使用你的 Web API 密钥对每个请求进行身份验证，该密钥作为 `Authorization: Bearer` 请求头发送。

在你运行客户端的终端中，将 API 密钥设置为环境变量：

```bash
export OXYLABS_WEB_API_KEY="your_api_key_here"
```

然后将服务器添加到你的客户端：

{% tabs %}
{% tab title="Claude Code" icon="claude" %}

```bash
claude mcp add --transport http --scope user oxylabs-web-api \\
  https://mcp.oxylabs.io/web-api-mcp \\
  --header "Authorization: Bearer ${OXYLABS_WEB_API_KEY}"
```

`--scope user` 使服务器在你的所有项目中可用。请确保 `OXYLABS_WEB_API_KEY` 在你启动 Claude Code 的环境中已设置。
{% endtab %}

{% tab title="ChatGPT/Codex" icon="openai" %}

```bash
codex mcp add oxylabs-web-api \\
  --url https://mcp.oxylabs.io/web-api-mcp \\
  --bearer-token-env-var OXYLABS_WEB_API_KEY
```

Codex 从 `OXYLABS_WEB_API_KEY` 环境变量中读取密钥，因此必须在你启动 Codex 的环境中设置它。
{% endtab %}

{% tab title="Cursor（及其他）" icon="cursor" %}
对于任何支持带自定义请求头的远程 MCP 服务器的客户端，请添加服务器 URL 和一个 `Authorization` 请求头到客户端的 MCP 配置中。例如，在 Cursor 的 `mcp.json`:

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "url": "https://mcp.oxylabs.io/web-api-mcp",
      "headers": {
        "Authorization": "Bearer ${env:OXYLABS_WEB_API_KEY}"
      }
    }
  }
}
```

字段名称可能因客户端而异——请查看客户端文档，了解如何添加带请求头的远程 MCP 服务器。
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**重要：** 你的 API 密钥授予对 Web API 使用情况的访问权限。不要提交包含它的配置文件，并在客户端支持时使用环境变量。
{% endhint %}

{% hint style="info" %}
**注意：** 仅支持通过 OAuth 登录远程服务器的客户端，例如 claude.ai 网页界面中的自定义连接器，无法发送自定义请求头，也无法连接到远程 MCP 服务器。请改用这些客户端的自托管选项。
{% endhint %}

### 选项 2：自托管 MCP

{% hint style="info" %}
**注意：** 本页中的远程和自托管命令使用相同的服务器名称， `oxylabs-web-api`。如果你从一种选项切换到另一种，请先从客户端中移除现有服务器。
{% endhint %}

将你的 Web API MCP 服务器自托管为以下任一形式： **本地（stdio）** 进程或 **共享服务器（HTTP）**:

{% tabs %}
{% tab title="本地（stdio）" %}

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

然后将你的客户端指向 `oxylabs-web-api-mcp` 命令。源代码可在 [Web API MCP GitHub 仓库](https://github.com/oxylabs/web-api-mcp).

<details>

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

```bash
claude mcp add oxylabs-web-api \\
  --env OXYLABS_WEB_API_KEY='${OXYLABS_WEB_API_KEY}' \\
  -- oxylabs-web-api-mcp
```

</details>

<details>

<summary><strong>Claude Desktop</strong></summary>

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "command": "oxylabs-web-api-mcp",
      "env": { "OXYLABS_ENV_FILE": "/absolute/path/to/.env" }
    }
  }
}
```

</details>

<details>

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

{% code overflow="wrap" expandable="true" %}

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

{% endcode %}

</details>

代理技能已经内置在服务器中。如果你更愿意单独管理技能，Claude Code 也可以改为采用 [skills](https://github.com/oxylabs/web-api-skills) 仓库作为插件，它会将此服务器和技能连接起来：

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

{% endtab %}

{% tab title="共享服务器（HTTP）" %}
为团队运行一个共享服务器，或为无法启动本地进程的代理运行：

```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" %}
**重要：** `MCP_ALLOWED_HOSTS` 是必需的——列出客户端连接的主机名，否则每个请求都会被拒绝，并返回 `421 Misdirected Request`。服务器本身没有认证，因此任何能够访问它的人都可以消耗其环境中设置的密钥：请将其置于 VPN 或经过认证的入口之后，绝不要暴露在公共互联网中。
{% endhint %}

端点为 `http://<host>:8080/mcp`。调用方可以在一个 `Authorization: Bearer` 请求头中发送自己的密钥。否则，服务器将使用 `OXYLABS_WEB_API_KEY`.

一个 `Dockerfile` 也可在 [仓库中找到](https://github.com/oxylabs/web-api-mcp)。要使用 Docker 运行服务器：

{% code overflow="wrap" expandable="true" %}

```bash
docker build -t oxylabs-web-api-mcp .
docker run --rm -p 8080:8080 \\
  -e OXYLABS_WEB_API_KEY \\
  -e MCP_ALLOWED_HOSTS='localhost:*,mcp.internal.example.com' \\
  oxylabs-web-api-mcp
```

{% endcode %}
{% endtab %}
{% endtabs %}

### 自托管 MCP 配置

<details>

<summary><strong>配置变量表</strong></summary>

<table><thead><tr><th width="231.22265625">变量</th><th width="413.6328125">说明</th><th>默认值</th></tr></thead><tbody><tr><td><code>OXYLABS_WEB_API_KEY</code></td><td>Web API 密钥，以以下形式发送： <code>Authorization: Bearer &#x3C;key></code>。在 stdio 中必需。通过 HTTP 时，每个请求的 <code>Authorization</code> 请求头优先。</td><td>–</td></tr><tr><td><code>OXYLABS_BASE_URL</code></td><td>覆盖 API 基础 URL，例如通过代理。</td><td><code>https://webapi.oxylabs.io</code></td></tr><tr><td><code>OXYLABS_RETRIES</code></td><td>在临时错误时重试（<code>429</code>, <code>500</code>, <code>502</code>, <code>503</code>, <code>504</code>).</td><td>2</td></tr><tr><td><code>OXYLABS_RATE_LIMIT</code></td><td>限制服务器的支出，例如 <code>100/1h</code> 或 <code>50/30m</code>.</td><td>关闭</td></tr><tr><td><code>OXYLABS_MAX_INLINE_TOKENS</code></td><td>超过此大小的内容（以 token 计）会保存到磁盘（stdio）或被截断（HTTP）。</td><td>10000</td></tr><tr><td><code>OXYLABS_SPILL_DIR</code></td><td>保存页面的写入位置（仅 stdio）。</td><td>系统临时目录</td></tr><tr><td><code>OXYLABS_SPILL</code></td><td>设为 <code>0</code> 以保持所有内容内联，即使在 stdio 下也是如此。</td><td>1</td></tr><tr><td><code>MCP_TRANSPORT</code></td><td><code>stdio</code> 或 <code>http</code>.</td><td><code>stdio</code></td></tr><tr><td><code>HOST</code> / <code>PORT</code></td><td>HTTP 绑定地址。</td><td><code>127.0.0.1</code> / <code>8080</code></td></tr><tr><td><code>MCP_ALLOWED_HOSTS</code></td><td>以逗号分隔的 <code>主机</code> 允许列表（仅 HTTP）。</td><td><code>localhost:*,127.0.0.1:*</code></td></tr><tr><td><code>MCP_ALLOWED_ORIGINS</code></td><td>以逗号分隔的 <code>来源</code> 浏览器客户端的允许列表（仅 HTTP）。</td><td>空</td></tr></tbody></table>

{% hint style="info" %}
开启 `stdio`时，服务器还会读取 `OXYLABS_*` 来自 `.env` 文件中的变量，或从以下位置设置的文件： `OXYLABS_ENV_FILE`。环境中已设置的变量优先。API 密钥在请求时读取，且绝不会写入磁盘或记录日志。
{% endhint %}

</details>

## Agent Browser

通过其 MCP 服务器连接 Agent Browser `hb-mcp`，让你的助手能够打开远程浏览器、浏览页面、与元素交互，并使用高级自主导航能力和 [**住宅代理**](https://oxylabs.io/products/residential-proxy-pool) 集成。你可以在以下位置找到所有详细信息： [Agent Browser MCP GitHub 仓库](https://github.com/oxylabs/oxylabs-ab-mcp).

### 可用工具

`hb_connect` 返回一个会话标签，你将其传递给其他工具，这样就可以并行运行多个会话。会话最长持续 1 小时，直到关闭前都会计入你的并发会话上限。

<table><thead><tr><th width="227">工具</th><th>作用</th></tr></thead><tbody><tr><td><code>hb_connect</code></td><td>打开会话——接受诸如 Agent Browser 参数，例如 <code>p_cc</code>, <code>p_device</code>, <code>p_src</code>, <code>p_fp_tag</code>, <code>session_name</code>, <code>o_profile</code>, <code>record</code>, <code>page_handler</code></td></tr><tr><td><code>hb_disconnect</code></td><td>关闭一个会话，或关闭所有会话</td></tr><tr><td><code>hb_session_info</code></td><td>列出已打开的会话，或显示其中一个的详细信息</td></tr><tr><td><code>hb_page_status</code>,<br><code>hb_page_handle</code>,<br><code>hb_classify_page</code></td><td>与 Page Handler 配合使用：读取页面状态，处理页面加载后出现的挑战（<code>hb_page_handle</code> 需要 <code>page_handler=true</code>），对当前页面进行分类</td></tr><tr><td><code>hb_sessions_list</code>,<br><code>hb_session_stop</code></td><td>列出并停止你账户中的实时会话</td></tr><tr><td><code>hb_recordings_list</code>,<br><code>hb_recording_url</code>,<br><code>hb_recording_delete</code></td><td>管理会话录制</td></tr><tr><td><code>hb_profiles_list</code>,<br><code>hb_profile_delete</code></td><td>管理持久化配置文件</td></tr><tr><td><code>hb_reference</code></td><td>返回参数和错误参考</td></tr><tr><td><code>browser_navigate</code></td><td>打开 URL</td></tr><tr><td><code>browser_snapshot</code></td><td>读取页面内容</td></tr><tr><td><code>browser_click</code></td><td>单击快照中的元素</td></tr><tr><td><code>browser_type</code>,<br><code>browser_fill_form</code></td><td>在一个字段中输入，或填写多个表单字段</td></tr><tr><td><code>browser_take_screenshot</code></td><td>捕获屏幕截图</td></tr><tr><td><code>browser_close</code></td><td>关闭会话</td></tr><tr><td>其他 <code>browser_*</code> 工具</td><td>标签页、悬停、按键、等待、文件上传、PDF 导出等更多功能</td></tr></tbody></table>

### 先决条件

* Agent Browser `username` 和 `password` 来自 [Oxylabs 仪表板](https://dashboard.oxylabs.io/).
* [Node.js](https://nodejs.org/) 20.0.0 或更高版本，以及 `git`.

### 安装

从 GitHub 安装服务器，因为它未发布到 `npm` 注册表：

{% code expandable="true" %}

```
npm install -g github:oxylabs/oxylabs-ab-mcp
```

{% endcode %}

然后将你的客户端指向 `hb-mcp` 二进制文件：

<details>

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

```bash
claude mcp add oxylabs-agent-browser \\
  -e OXY_HB_USERNAME="USERNAME" \\
  -e OXY_HB_PASSWORD="PASSWORD" \\
  -- hb-mcp
```

</details>

<details>

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

将此添加到你的 `claude_desktop_config.json` 或 `.mcp.json` 文件：

```json
{
  "mcpServers": {
    "oxylabs-agent-browser": {
      "command": "hb-mcp",
      "env": {
        "OXY_HB_USERNAME": "USERNAME",
        "OXY_HB_PASSWORD": "PASSWORD"
      }
    }
  }
}
```

</details>

若要跳过全局安装，请使用 `npx -y github:oxylabs/oxylabs-ab-mcp` 作为命令，而不是 `hb-mcp`。启动会更慢。

#### 位置选择

让你的助手使用以下方式在特定国家/地区打开浏览器： `p_cc` 参数，或使用以下方式为每个会话设置默认值： `--default-params` 参数：

```json
"oxylabs-agent-browser": {
  "command": "hb-mcp",
  "args": ["--default-params", "p_cc=US"],
  "env": {
    "OXY_HB_USERNAME": "USERNAME",
    "OXY_HB_PASSWORD": "PASSWORD"
  }
}
```

要选择浏览器的位置选项，请访问 [地理位置与代理选择](/products/agent-browser/geolocation-and-proxy-selection.md) 页面。如果未指定位置，将根据可用性自动分配一个。

## 将多个产品一起使用

你可以在同一个客户端中运行两个服务器。将它们的条目合并到一个 `mcpServers` 对象中。

<details>

<summary>示例</summary>

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "command": "oxylabs-web-api-mcp",
      "env": { "OXYLABS_WEB_API_KEY": "${env:OXYLABS_WEB_API_KEY}" }
    },
    "oxylabs-agent-browser": {
      "command": "hb-mcp",
      "env": {
        "OXY_HB_USERNAME": "${env:OXY_HB_USERNAME}",
        "OXY_HB_PASSWORD": "${env:OXY_HB_PASSWORD}"
      }
    }
  }
}
```

如需改用 Web API 的 Remote MCP 服务器，请将 `oxylabs-web-api` 条目替换为来自 [选项 1](#option-1-remote-mcp)的远程条目，在支持带有 header 的远程服务器的客户端中。

</details>

## 验证设置

1. 检查你的服务器是否在客户端的 MCP 列表中显示为已启用（在 Claude Code 中，运行 `/mcp`，或者在 Codex 中运行 `codex mcp list`).
2. 为你设置的每个产品发送一个测试提示，如果出现提示则批准工具调用（例如 `搜索网页中的“oxylabs”并显示前三个结果。`).

{% hint style="success" %}
**注意：** 即使 API 密钥缺失或不正确，服务器也可能显示为已连接并列出其工具。密钥只会在工具运行时检查，因此只有测试提示才能确认你的设置是否有效。
{% endhint %}

## 故障排查

<table><thead><tr><th width="341.37109375">问题</th><th>解决方案</th></tr></thead><tbody><tr><td>服务器未出现在客户端中</td><td>请确保 JSON 有效，然后重启应用。如果你使用了命令，请再次运行并检查服务器列表。</td></tr><tr><td>服务器已连接且工具已列出，但工具调用失败</td><td>API 密钥只会在工具运行时检查。请确认密钥正确，并且你使用的是对应产品的凭据：Web API 使用 API 密钥，Agent Browser 使用用户名和密码。</td></tr><tr><td><code>身份验证失败（401）</code></td><td>Web API 密钥无效。请从你的 Web API 实例顶部再次复制它，位于 <a href="https://dashboard.oxylabs.io/">仪表板</a>.</td></tr><tr><td rowspan="2">提示未提供 Web API 密钥</td><td>Remote MCP： <code>Authorization</code> header 缺失，或 <code>OXYLABS_WEB_API_KEY</code> 在你启动客户端的环境中为空——请先设置它，然后重启客户端。 </td></tr><tr><td>自托管：密钥未在服务器环境中设置。</td></tr><tr><td>Remote MCP 服务器无法连接，或者你的客户端无法设置 header</td><td>你的客户端可能只支持远程服务器的 OAuth 登录，或者不支持自定义 header。请使用 <a href="#option-2-self-hosted-mcp">自托管</a> 选项。</td></tr><tr><td>页面内容被截断</td><td>当服务器通过 HTTP 运行时，超过 token 限制的页面会被截断，这也包括 Remote MCP。请仅使用 <code>json_prompt</code>，或者在本地运行自托管服务器（<code>stdio</code>），这样会将大页面保存到磁盘，供代理分块读取。</td></tr><tr><td><code>oxylabs-web-api-mcp</code>：未找到命令（自托管）</td><td>安装 <code>uv</code> 以及 Python 3.10 或更高版本，安装服务器，并确保 <code>uv</code> 工具目录位于你的 <code>PATH</code> (<code>uv tool update-shell</code>).</td></tr><tr><td><code>421 Misdirected Request</code> （自托管 HTTP 服务器）</td><td>将客户端连接的主机名添加到 <code>MCP_ALLOWED_HOSTS</code>.</td></tr><tr><td><code>hb-mcp</code> 或 <code>npx</code>：未找到命令</td><td>安装 <a href="https://nodejs.org/">Node.js</a> 20.0.0 或更高版本，以及 <code>git</code>，并确保它们位于你的 <code>PATH</code>.</td></tr><tr><td>Agent Browser 无法连接</td><td>请验证你的凭据，并确保防火墙没有干扰 WebSocket 连接。</td></tr><tr><td>Cursor 菜单看起来不同</td><td>编辑 <code>mcp.json</code> 直接编辑——菜单标签可能会因 Cursor 版本而变化。请查看以下位置的日志： <strong>输出 → MCP 日志</strong>.</td></tr></tbody></table>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/ai-workflows/cn/mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.