内容
# 隐身浏览器 MCP
隐身浏览器 MCP 是一个 Python MCP 服务器，允许代理控制由隐身浏览器支持的浏览器，适用于 Linux 服务器、CI 作业和其他无法使用普通桌面浏览器的环境。
它设计了三种运行时模式：
- 无头 Linux 浏览，无需 `$DISPLAY`
- 通过 Xvfb 进行虚拟显示浏览，需要浏览器头部行为
- 与现有的隐身浏览器或 Chromium 兼容的端点建立 CDP 连接
服务器通过 MCP 标准输入/输出暴露浏览器自动化工具，因此 Claude Code 等客户端可以启动会话、导航、检查页面、与表单交互、管理 cookie/存储，并处理多个选项卡。
## 上游
该项目是一个 MCP 包装器和面向代理的扩展，构建在 [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser) 之上。CloakBrowser 提供了底层浏览器启动和反检测自动化层；该存储库添加了 MCP 服务器、工具模式、会话生命周期、Linux 无头/虚拟显示部署流程、测试和面向代理的文档。
## 功能
- 28 个 MCP 工具用于浏览器会话、页面交互、cookie、存储状态和多页面工作流。
- 默认情况下在无头 Linux 环境中工作。
- 可选的 Xvfb 支持虚拟显示会话。
- 可选的 CDP 后端，用于连接到现有的浏览器服务。
- 隐身浏览器启动选项，用于用户代理、视口、代理、本地化、时区、地理位置、人类化、扩展、头部、权限和持久配置文件/状态。
- 通过 `browser_select_option(...,
frame_selector="iframe#...")` 支持 iframe 感知选择。
- `uv` 管理的本地开发和部署。
## 要求
- Python 3.11 或更新版本
- `uv`
- Linux、macOS 或其他受 Python 依赖项支持的平台
- 对于 Linux 上的虚拟显示模式：`Xvfb`
如有需要，请安装 `uv`：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
对于 Debian/Ubuntu 上的虚拟显示模式：
```bash
sudo apt-get update
sudo apt-get install -y xvfb
```
如果运行时没有可用的浏览器二进制文件，请安装 Playwright Chromium 浏览器：
```bash
uv run python -m playwright install chromium
```
## 安装
克隆存储库并创建一个隔离的 `uv` 环境：
```bash
git clone https://github.com/SJF-ECNU/CloakBrowserMCP.git
cd CloakBrowserMCP
uv sync --extra dev --no-editable
```
项目依赖于：
- [`cloakbrowser>=0.4,<1`](https://github.com/CloakHQ/CloakBrowser)
- `mcp[cli]>=1.28,<2`
- `pyvirtualdisplay>=3,<4`
更改源代码后，请重新构建 MCP 客户端使用的已安装包：
```bash
uv sync --extra dev --no-editable --reinstall-package cloakbrowser-mcp
```
## 运行 MCP 服务器
启动标准输入/输出 MCP 服务器：
```bash
uv run --no-editable cloakbrowser-mcp
```
该进程通过标准输入/输出进行通信。通常由 MCP 客户端启动，而不是在终端中手动运行。
## Claude Code 设置
从存储库根目录，注册服务器：
```bash
claude mcp add --scope user cloakbrowser -- \
uv --project "$PWD" run --no-editable cloakbrowser-mcp
```
然后重启 Claude Code 或重新连接 MCP 服务器。在 Claude Code 中运行 `/mcp` 并确认 `cloakbrowser` 已连接。
如果您编辑服务器代码，请重新安装软件包并重新连接 Claude Code：
```bash
uv sync --extra dev --no-editable --reinstall-package cloakbrowser-mcp
```
Claude Code 可能会在连接生命周期内缓存 MCP 工具模式，因此建议在工具签名更改后重启/重新连接。
## 通用 MCP 客户端配置
对于读取 JSON MCP 配置的客户端，请使用以下配置：
```json
{
"mcpServers": {
"cloakbrowser": {
"command": "uv",
"args": [
"--project",
"/absolute/path/to/CloakBrowserMCP",
"run",
"--no-editable",
"cloakbrowser-mcp"
]
}
}
}
```
将 `/absolute/path/to/CloakBrowserMCP` 替换为本地检出路径。
## 浏览器模式
### 无头模式
这是默认模式，是 Linux 服务器无显示时的最佳选择：
```json
{
"display_mode": "headless"
}
```
### 虚拟显示模式
当目标网站需要浏览器头部行为时，请使用此模式。如果已设置 `$DISPLAY`，服务器将使用它。否则，它将启动 Xvfb。
```json
{
"display_mode": "virtual"
}
```
### CDP 模式
使用 CDP 模式连接到现有的浏览器或隐身浏览器服务：
```json
{
"backend": "cdp",
"cdp_url": "http://127.0.0.1:9222",
"fingerprint": "agent-session-1"
}
```
您也可以设置默认 CDP URL：
```bash
export CLOAK_MCP_DEFAULT_CDP_URL=http://127.0.0.1:9222
```
## 工具概览
会话工具：
- `browser_start`
- `browser_close`
页面基础：
- `browser_navigate`
- `browser_click`
- `browser_type`
- `browser_evaluate`
- `browser_snapshot`
- `browser_screenshot`
页面操作：
- `browser_wait_for_selector`
- `browser_press`
- `browser_hover`
- `browser_select_option`
- `browser_get_text`
- `browser_get_attribute`
- `browser_get_links`
- `browser_scroll`
- `browser_reload`
- `browser_go_back`
- `browser_go_forward`
上下文和页面管理：
- `browser_get_cookies`
- `browser_set_cookies`
- `browser_clear_cookies`
- `browser_get_storage_state`
- `browser_save_storage_state`
- `browser_new_page`
- `browser_list_pages`
- `browser_switch_page`
- `browser_close_page`
## 常见工作流
### 启动和导航
```json
{
"tool": "browser_start",
"arguments": {
"display_mode": "headless",
"viewport": {"width": 1440, "height": 900},
"locale": "zh-CN",
"timezone": "UTC"
}
}
```
然后导航：
```json
{
"tool": "browser_navigate",
"arguments": {
"session_id": "<session_id>",
"url": "https://example.com",
"wait_until": "domcontentloaded"
}
}
```
### 检查页面
使用 `browser_snapshot` 获取 URL、标题和可见文本。使用 `browser_get_text` 获取所有可见文本或特定选择器的文本提取：
```json
{
"tool": "browser_get_text",
"arguments": {
"session_id": "<session_id>",
"selector": "main"
}
}
```
### 搜索或填写表单
```json
{
"tool": "browser_type",
"arguments": {
"session_id": "<session_id>",
"selector": "input[name=q]",
"text": "隐身浏览器 MCP"
}
}
```
```json
{
"tool": "browser_press",
"arguments": {
"session_id": "<session_id>",
"selector": "input[name=q]",
"key": "Enter"
}
}
```
### 在 iframe 中选择选项
对于普通的页面级 `<select>`，省略 `frame_selector`。对于 iframe 内的选择，单独传递 iframe 选择器：
```json
{
"tool": "browser_select_option",
"arguments": {
"session_id": "<session_id>",
"selector": "#size",
"value": "medium",
"frame_selector": "iframe#preview"
}
}
```
### 重用登录状态
保存存储状态：
```json
{
"tool": "browser_save_storage_state",
"arguments": {
"session_id": "<session_id>",
"path": "/tmp/cloak-state.json"
}
}
```
使用该状态启动新会话：
```json
{
"tool": "browser_start",
"arguments": {
"storage_state": "/tmp/cloak-state.json"
}
}
```
对于持久性浏览器配置文件，请使用 `profile_dir` 代替。`profile_dir` 和 `storage_state` 是互斥的。
## `browser_start` 选项
| 选项 | 类型 | 备注 |
| --- | --- | --- |
| `backend` | 字符串 | `direct` 或 `cdp`。默认为 `direct`。 |
| `display_mode` | 字符串 | `headless`、`virtual` 或 `cdp`。默认为 `headless`。 |
| `headless` | 布尔值/空 | 覆盖直接模式下的无头行为。 |
| `proxy` | 字符串/空 | 代理 URL 转发到隐身浏览器。 |
| `locale` | 字符串/空 | 浏览器本地化，例如 `zh-CN`。 |
| `timezone` | 字符串/空 | 浏览器时区，例如 `UTC`。 |
| `humanize` | 布尔值 | 启用隐身浏览器人类化行为。 |
| `profile_dir` | 字符串/空 | 持久性配置文件目录。 |
| `cdp_url` | 字符串/空 | CDP 模式下必填，除非设置了环境变量。 |
| `fingerprint` | 字符串/空 | 添加到 CDP URL 作为 `fingerprint` 查询参数。 |
| `user_agent` | 字符串/空 | 自定义用户代理。 |
| `viewport` | 对象/空 | 示例：`{"width": 1440, "height": 900}`。 |
| `no_viewport` | 布尔值 | 将 Playwright 视口设置为 `null`。 |
| `color_scheme` | 字符串/空 | `light`、`dark` 或 `no-preference`。 |
| `geoip` | 布尔值 | 转发隐身浏览器 geoip 选项。 |
| `stealth_args` | 布尔值 | 默认为 `true`。 |
| `args` | 数组/空 | 额外的浏览器启动参数。 |
| `extension_paths` | 数组/空 | 浏览器扩展路径。 |
| `human_preset` | 字符串 | 隐身浏览器人类化预设。 |
| `human_config` | 对象/空 | 隐身浏览器人类化配置。 |
| `storage_state` | 字符串/对象/空 | 存储状态路径或对象。 |
| `extra_http_headers` | 对象/空 | 额外的 HTTP 头部。 |
| `permissions` | 数组/空 | 浏览器上下文权限。 |
环境变量：
- `CLOAK_MCP_DEFAULT_DISPLAY_MODE`: 默认显示模式（当未提供时）
- `CLOAK_MCP_DEFAULT_CDP_URL`: 默认 CDP 端点
- `CLOAK_MCP_SCREENSHOT_DIR`: 截图输出目录
## 开发
安装开发依赖项：
```bash
uv sync --extra dev
```
在源代码树上运行测试：
```bash
PYTHONPATH=src uv run pytest -q
```
在已安装的软件包上运行测试：
```bash
uv sync --extra dev --no-editable --reinstall-package cloakbrowser-mcp
uv run --no-editable pytest -q
```
真实浏览器烟雾测试是可选的：
```bash
CLOAK_MCP_RUN_SMOKE=1 uv run --no-editable pytest tests/test_smoke.py -q
```
虚拟显示烟雾测试：
```bash
CLOAK_MCP_RUN_VIRTUAL_SMOKE=1 uv run --no-editable pytest tests/test_smoke.py -q
```
CDP 烟雾测试：
```bash
CLOAK_MCP_SMOKE_CDP_URL=http://127.0.0.1:9222 \
uv run --no-editable pytest tests/test_smoke.py -q
```
## 安全注意事项
浏览器自动化可以访问网页、cookie、浏览器配置文件引用的本地文件和身份验证会话。请在适合代理和目标网站信任级别的环境中运行 MCP 服务器。
避免与不受信任的代理共享持久性 `profile_dir` 或 `storage_state` 文件。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
