# 与 MCP 集成

本指南说明如何集成 [**Oxylabs Headless Browser**](https://oxylabs.io/products/headless-browser) 与 MCP（Model Context Protocol），以便让 AI 系统与远程浏览器交互并对其进行控制。

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

## 概述

Model Control Protocol (MCP) 允许 Claude 等 AI 系统与浏览器交互并执行基于 Web 的任务。通过集成 [**Oxylabs Headless Browser**](https://oxylabs.io/products/unblocking-browser) 与 MCP，您可以利用 AI 系统执行 **网页导航、数据检索和自动化** 任务，使用具备高级隐蔽能力的远程浏览器，以及 [**Residential Proxy**](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）连接到 Headless Browser。

<figure><img src="https://2655358775-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzrXw45naRpCZ0Ku9AjY1%2Fuploads%2FzUoGJVOHkxw5QSB9VvQF%2FMCP%20and%20UB%20integration%20scheme.png?alt=media&#x26;token=20fa95e8-0fd7-4ad3-8b3f-becc97bac3d5" alt=""><figcaption></figcaption></figure>

## 开始使用

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

1. **Oxylabs 账户**：获取用于 Oxylabs Headless Browser 的用户名和密码。&#x20;

{% hint style="info" %}
目前，您可以通过我们的销售联系获取 Headless Browser： [**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 Host**：已安装 Claude Desktop 或 Cursor。

## 配置 MCP 服务器

使用您的 Oxylabs 凭据创建一个 MCP 服务器配置块。将 `<username>` 和 `<password>` 替换为您的实际 Oxylabs 凭据：

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubs.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

## 高级配置选项

### 国家选择

您可以通过在连接 URL 中添加 `?p_cc` 参数，为浏览器会话指定国家：

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubs.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 %}

### 美国基础设施

对于主要在美国运营的用户，您可以直接连接到美国基础设施，以获得更快的加载时间：

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubs-us.oxylabs.io"
  ]
}
```

{% hint style="warning" %}
此方案主要缩短美国用户的响应时间，不应与代理地理位置选择混淆。
{% endhint %}

### 浏览器参数（仅限 Chrome）

对于基于 Chrome 的 Headless Browser，您可以使用 `bargs` 参数指定额外的浏览器参数：

```json
"oxylabs_headless_browser": {
  "command": "npx",
  "args": [
    "@playwright/mcp@latest",
    "--cdp-endpoint",
    "wss://<username>:<password>@ubc.oxylabs.io/?bargs=force-color-profile:srgb&bargs=window-position:100,100"
  ]
}
```

支持的参数包括：

* `force-color-profile:<profile>`：强制将所有显示器视为使用指定的颜色配置文件
* `window-position:X,Y`：指定初始窗口位置
* `hide-scrollbars`：阻止为网页内容创建滚动条
* `enable-features:<feature1>,<feature2>,<feature3>`：以逗号分隔的要启用的功能名称列表
* `disable-notifications`：禁用 Web Notification 和 Push API

## 故障排查

如果您在集成时遇到问题：

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