# 与 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 系统与浏览器交互并执行基于网页的任务。通过将 [**Oxylabs 无头浏览器**](https://oxylabs.io/products/unblocking-browser) 与 MCP 集成，您可以实现 AI 系统执行 **网页导航、数据检索和自动化** 任务，使用具备高级隐匿能力和 [**住宅代理**](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）连接到无头浏览器。
## 入门
在设置集成之前，请确保您已具备：
1. **Oxylabs 账户**：获取您的 Oxylabs 无头浏览器用户名和密码。
{% 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 服务器配置块。将 `` 和 `` 替换为您实际的 Oxylabs 凭据：
```json
"oxylabs_headless_browser": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--cdp-endpoint",
"wss://:@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` 参数到您的连接 URL：
```json
"oxylabs_headless_browser": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--cdp-endpoint",
"wss://:@ubs.oxylabs.io?p_cc=US"
]
}
```
将 `US` 替换为您希望使用的 ISO-3166 国家代码。如果未指定国家，系统将根据可用性自动分配。
{% 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://:@ubs-us.oxylabs.io"
]
}
```
{% hint style="warning" %}
此方案主要缩短美国用户的响应时间，不应与代理地理位置选择混淆。
{% endhint %}
### 浏览器参数（仅限 Chrome）
对于基于 Chrome 的无头浏览器，您可以使用 `bargs` 参数来抑制警告/错误：
```json
"oxylabs_headless_browser": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--cdp-endpoint",
"wss://:@ubc.oxylabs.io/?bargs=force-color-profile:srgb&bargs=window-position:100,100"
]
}
```
支持的参数包括：
* `force-color-profile:`：强制将所有显示器视为使用指定的颜色配置文件
* `window-position:X,Y`：指定初始窗口位置
* `hide-scrollbars`：防止为网页内容创建滚动条
* `enable-features:,,`：以逗号分隔的要启用的功能名称列表
* `disable-notifications`：禁用 Web Notification 和 Push API
## 故障排除
如果您在集成过程中遇到问题：
1. **连接问题**:
* 验证您的 Oxylabs 凭据
* 检查您的网络连接
* 确保防火墙未阻止 WebSocket 连接
2. **性能问题**:
* 对于美国用户，请尝试使用美国专用端点
* 如果需要，请增加配置中的超时时间
3. **浏览器未加载**:
* 检查 Node.js 版本（必须是 18.0.0 或更高）
* 验证 npx 是否已正确安装
* 重启 MCP 主机应用程序
---
# Agent Instructions: 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/cn/headless-browser/integration-with-mcp.md?ask=
```
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.