> 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/cn/headless-browser/ai-gong-zuo-liu/integration-with-mcp.md).

# 与 MCP 集成

本指南将说明如何集成 [**Oxylabs 无头浏览器**](https://oxylabs.io/products/headless-browser) 与 MCP（模型上下文协议）结合，以使 AI 系统能够与远程浏览器交互并控制它们。

{% hint style="success" %}
请访问 Oxylabs GitHub 仓库，查看以下内容的完整可运行示例： [**与 Oxylabs 无头浏览器的 MCP 集成**](https://github.com/oxylabs/oxylabs-hb-mcp)**.**
{% endhint %}

## 概述

模型上下文协议（MCP）允许像 Claude 这样的 AI 系统与浏览器交互并执行基于 Web 的任务。通过集成 [**Oxylabs 无头浏览器**](https://oxylabs.io/products/unblocking-browser) 与 MCP，你可以实现 AI 系统来执行 **Web 导航、数据检索和自动化** 任务，使用具备高级自主导航能力和 [**住宅代理**](https://oxylabs.io/products/residential-proxy-pool) 集成。

MCP 主机（例如 [**Claude Desktop**](https://claude.ai/download) 或 [**Cursor**](https://www.cursor.com/)）自带内置的 MCP 客户端。Playwright-MCP 作为 MCP 服务器运行，不使用本地浏览器，而是通过安全的 WebSocket 连接（WSS）连接到无头浏览器。

<figure><img src="/files/cac4f1a6668fd31c284d7209ad61abd25d48c52f" alt=""><figcaption></figcaption></figure>

## 快速开始

在设置集成之前，请确保你已具备：

1. **Oxylabs 账户**: 获取用于 Oxylabs 无头浏览器的用户名和密码。&#x20;

{% hint style="info" %}
目前，你可以通过我们的销售团队获取无头浏览器，联系 [**hello@oxylabs.io**](mailto:hello@oxylabs.io)**.**
{% endhint %}

2. **Node.js**: 版本 `18.0.0` 或更高（包含 npm/npx）

* **Windows**: 从 [**nodejs.org**](https://nodejs.org/)
* **macOS**: 使用 Homebrew（`brew install node`）或从 [**nodejs.org**](https://nodejs.org/)
* **Linux**:
  * Ubuntu/Debian： `sudo apt update && sudo apt install nodejs npm`
  * Fedora： `sudo dnf install nodejs npm`
  * 或从 [**nodejs.org**](https://nodejs.org/)

3. **MCP 主机**：已安装 Claude Desktop 或 Cursor。

## 配置 MCP 服务器

使用你的 Oxylabs 凭据创建一个 MCP 服务器配置部分。将 `USERNAME` 和 `PASSWORD` 替换为你实际的 Oxylabs 凭据：

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

### 选项 1：与 Cursor 集成

1. 打开 Cursor
2. 打开 Cursor 设置
3. 选择 MCP
4. 添加准备好的 MCP 服务器配置
5. 重启 Cursor

### 选项 2：与 Claude Desktop 集成

1. 打开 Claude Desktop
2. 打开 Claude Desktop 设置
3. 进入 Developer
4. 点击 Edit Config
5. 编辑 `claude_desktop_config.json` 文件
6. 添加准备好的 MCP 服务器配置
7. 重启 Claude Desktop

## 高级配置选项

### 国家选择

您可以通过添加以下内容为浏览器会话指定国家/地区： `?p_cc` 参数添加到你的连接 URL：

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

将 `US` 替换为你想要的 SO-3166 国家代码。如果未指定国家，系统会根据可用性自动分配一个。&#x20;

{% hint style="success" %}
你可以在这里找到 **ISO-3166 国家代码** [**列表**](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).
{% endhint %}

你也可以使用 `p_state` 或 `p_city` 进行州（US）或城市级定位，或使用粘性住宅代理实现更精细的出口 IP 控制。了解更多 [**列表**](/products/cn/headless-browser/di-li-wei-zhi-yu-dai-li-xuan-ze.md).

## 故障排查

如果你在集成中遇到问题：

1. **连接问题**:
   * 验证你的 Oxylabs 凭据
   * 检查你的网络连接
   * 确保防火墙没有阻止 WebSocket 连接
2. **性能问题**:
   * 对于美国用户，尝试使用美国专用端点
   * 如有需要，在配置中增加超时时间
3. **浏览器未加载**:
   * 检查 Node.js 版本（必须为 18.0.0 或更高）
   * 验证 npx 是否已正确安装
   * 重启 MCP 主机应用


---

# 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/products/cn/headless-browser/ai-gong-zuo-liu/integration-with-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.