内容
# 浏览器 MCP 服务器模板
用于自动化的浏览器 MCP 服务器模板。适用于任何支持 MCP 的 LLM（Claude、GPT、Gemini、Mistral 等）。
## 功能
| 功能 | 描述 |
|---------|----------|
| **隐身模式** | 通过 puppeteer-extra-plugin-stealth 进行反检测 |
| **自动配置文件** | 自动搜索带有 Cookie 的配置文件 |
| **连接** | 连接到已经运行的浏览器 |
| **16 种规避方法** | 伪装成普通浏览器 |
### 隐身模式（保护免受验证码干扰）
服务器使用 `puppeteer-extra-plugin-stealth` 来绕过自动化检测：
- 隐藏 `navigator.webdriver`
- 添加 `chrome.runtime`
- 模拟插件、语言、权限
- 伪装 User-Agent
- 等等
```javascript
// 检查隐身模式
browser_check_stealth()
// 在 bot.sannysoft.com 上测试
browser_navigate({ url: "https://bot.sannysoft.com/" })
```
## 支持的浏览器
| 浏览器 | 状态 | 备注 |
|---------|--------|------------|
| Google Chrome | ✅ | 推荐 |
| Chromium | ✅ | |
| Microsoft Edge | ✅ | |
| Brave | ✅ | |
| Opera | ✅ | |
| Firefox | ⚠️ | 基本支持 |
自动查找已安装的浏览器。优先级：Chrome > Chromium > Edge > Brave > Opera > Firefox。
## 安装
```bash
cd /root/browser-mcp-template
npm install
# 安装 Chrome/Chromium（如果需要）
npx puppeteer browsers install chrome
```
### 指定特定浏览器
通过环境变量：
```bash
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/firefox"
```
## 使用
### Claude Desktop
在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/root/browser-mcp-template/index.js"]
}
}
}
```
### Claude Code（CLI）
```bash
claude mcp add browser node /root/browser-mcp-template/index.js
```
### Cursor / Windsurf / VS Code
在 MCP 设置中添加：
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/path/to/browser-mcp-template/index.js"]
}
}
}
```
## 可用工具
### 导航和控制
| 工具 | 描述 |
|------------|----------|
| `browser_navigate` | 打开 URL（选择浏览器和配置文件） |
| `browser_click` | 点击元素 |
| `browser_type` | 在字段中输入文本 |
| `browser_screenshot` | 截取屏幕截图 |
| `browser_get_text` | 获取元素文本 |
| `browser_get_html` | 获取元素 HTML |
| `browser_evaluate` | 执行 JavaScript |
| `browser_wait` | 等待元素或时间 |
| `browser_select` | 在下拉列表中选择选项 |
| `browser_scroll` | 滚动页面 |
| `browser_hover` | 将光标悬停在元素上 |
| `browser_upload` | 上传文件 |
| `browser_press` | 按下按键 |
### 标签页和信息
| 工具 | 描述 |
|------------|----------|
| `browser_list_tabs` | 打开的标签页列表 |
| `browser_switch_tab` | 切换标签页 |
| `browser_get_info` | 页面 URL 和标题 |
| `browser_get_browser_info` | 浏览器信息 |
| `browser_check_stealth` | 检查隐身模式 |
| `browser_close` | 关闭浏览器 |
### 配置文件和 Cookie
| 工具 | 描述 |
|------------|----------|
| `browser_auto_connect` | 自动检测带有 Cookie 的配置文件并启动浏览器 |
| `browser_list_profiles` | 可用的浏览器配置文件列表 |
| `browser_detect_active_profile` | 确定正在使用的配置文件 |
| `browser_get_cookies` | 获取当前会话的 Cookie |
| `browser_set_cookie` | 设置 Cookie |
| `browser_delete_cookie` | 删除 Cookie |
| `browser_connect` | 连接到已经运行的浏览器 |
| `browser_start_with_debug` | 启动带有调试端口的浏览器 |
## 配置文件操作
### 自动检测配置文件（最简单的方法！）
```javascript
// 自动查找带有 Cookie 的配置文件并启动浏览器
browser_auto_connect({
browser: "chrome",
url: "https://github.com" // 可选
})
// 或通过 browser_navigate 使用 profile="auto"
browser_navigate({
url: "https://github.com",
profile: "auto" // 自动检测配置文件
})
```
服务器自动：
1. 在标准路径中查找 Chrome/Firefox/Edge/Brave 配置文件
2. 读取 `Local State` 以查找最近使用的配置文件
3. 检查 Cookie 文件是否存在
4. 使用找到的配置文件启动浏览器
### 连接到已经运行的浏览器（最简单的方法！）
如果 Chrome 已经打开并授权，连接它：
```bash
# 1. 使用调试端口启动 Chrome（一次）
google-chrome --remote-debugging-port=9222
# 2. 通过 MCP 连接
browser_connect({ port: 9222 })
```
或通过 MCP 启动浏览器：
```javascript
browser_start_with_debug({
browser: "chrome",
port: 9222,
profile: "default" // 使用现有配置文件
})
// 然后连接
browser_connect({ port: 9222 })
```
**重要**: 当 `browser_close()` 时，服务器会断开与浏览器的连接，但 **不会** 关闭它 - 您可以继续手动在浏览器中工作。
### 自动检测活动配置文件
```javascript
// 确定正在使用的配置文件
browser_detect_active_profile({ browser: "chrome" })
// 返回：配置文件名称、路径、是否有 Cookie、浏览器是否正在运行
```
### 使用真实配置文件（带有 Cookie 和授权）
```javascript
// 使用 Chrome 默认配置文件（所有 Cookie 和会话）
browser_navigate({
url: "https://github.com",
profile: "default"
})
// 使用特定配置文件
browser_navigate({
url: "https://github.com",
profile: "default",
profileName: "Profile 1"
})
// 指定自定义配置文件路径
browser_navigate({
url: "https://github.com",
profile: "custom",
profilePath: "/home/user/.config/google-chrome"
})
// 无配置文件（干净的会话）
browser_navigate({
url: "https://github.com",
profile: "none"
})
```
### 查看可用配置文件
```javascript
// 查找所有 Chrome 配置文件
browser_list_profiles({ browser: "chrome" })
// 确定活动配置文件
browser_detect_active_profile({ browser: "chrome" })
```
### 使用 Cookie
```javascript
// 查看所有 Cookie
browser_get_cookies()
// 特定域名的 Cookie
browser_get_cookies({ url: "https://github.com" })
// 设置 Cookie
browser_set_cookie({
name: "session",
value: "abc123",
domain: ".github.com"
})
// 删除 Cookie
browser_delete_cookie({
name: "session",
domain: ".github.com"
})
```
### 环境变量
```bash
# 指定配置文件路径
export BROWSER_PROFILE_PATH="~/.config/google-chrome"
# 指定浏览器路径
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/google-chrome"
```
## 使用示例（LLM 提示）
```
使用我的配置文件（profile="default"）打开 GitHub，查找我的仓库并创建一个新问题。
```
```
使用授权网站。 使用 profile="default" 保存会话。
登录后获取 Cookie 并保存它们。
```
## 自动化示例
```bash
# 通过 MCP 的操作链示例：
1. browser_navigate(url="https://github.com", profile="default")
2. browser_click(selector="a[href='/login']")
3. browser_wait(selector="input[name='login']", timeout=5000)
4. browser_type(selector="input[name='login']", text="myuser")
5. browser_type(selector="input[name='password']", text="mypass")
6. browser_click(selector="input[type='submit']")
7. browser_wait(selector=".dashboard", timeout=10000)
8. browser_screenshot()
```
## 要求
- Node.js 18+
- 浏览器之一：Chrome、Chromium、Edge、Brave、Opera 或 Firefox
- ~200MB 浏览器空间
### 自动浏览器检测
服务器自动在标准路径中查找浏览器：
- `/usr/bin/google-chrome`
- `/snap/bin/chromium`
- `/usr/bin/microsoft-edge`
- `/usr/bin/brave-browser`
- `/usr/bin/firefox`
### 自动配置文件检测
服务器在标准路径中查找配置文件：
- Chrome：`~/.config/google-chrome`、`~/.config/chromium`
- Firefox：`~/.mozilla/firefox`
- Edge：`~/.config/microsoft-edge`
- Brave：`~/.config/BraveSoftware/Brave-Browser`
如果配置文件位于非标准位置，请指定 `BROWSER_PROFILE_PATH`。
### 重要
使用真实配置文件时，**不要** 同时启动两个浏览器 - 这可能会损坏数据。 如果浏览器已经打开，请在启动 MCP 服务器之前手动关闭它。
## 许可证
MIT
