内容
# 浏览器MCP服务器
一个生产就绪的[模型上下文协议（MCP）](https://modelcontextprotocol.io)服务器，通过Chrome扩展程序将AI助手连接到本地浏览器。
> 从Cursor、Claude Desktop、VS Code、Windsurf和任何MCP兼容的客户端控制导航、交互、快照和截图，无需启动单独的浏览器实例。
---
## 目录
- [概述](#概述)
- [架构](#架构)
- [功能](#功能)
- [要求](#要求)
- [安装](#安装)
- [配置](#配置)
- [开发](#开发)
- [测试](#测试)
- [项目结构](#项目结构)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [常见问题](#常见问题)
- [许可证](#许可证)
---
## 概述
浏览器MCP将AI客户端（通过stdio MCP传输）连接到Chrome扩展程序（通过本地WebSocket）。扩展程序在您的**现有浏览器配置文件**上运行，保留登录会话并减少与无头自动化的机器人检测摩擦。
```mermaid
flowchart TB
subgraph Client["AI Client"]
MCP["MCP Host\n(Cursor / Claude / VS Code)"]
end
subgraph Server["MCP Server (this repo)"]
STDIO["Stdio Transport"]
CORE["Tool Handler"]
WS["WebSocket Bridge :9009"]
REDIS[("Redis\n(optional)")]
end
subgraph Browser["User Browser"]
EXT["Chrome Extension"]
TAB["Active Tab"]
end
MCP <-->|JSON-RPC stdio| STDIO
STDIO --> CORE
CORE --> WS
CORE -.->|session metadata| REDIS
WS <-->|typed messages| EXT
EXT --> TAB
```
---
## 架构
### 请求流程
```mermaid
sequenceDiagram
participant AI as AI Client
participant MCP as MCP Server
participant WS as WebSocket
participant EXT as Chrome Extension
participant Page as Browser Tab
AI->>MCP: tools/call browser_navigate
MCP->>WS: browser_navigate { url }
WS->>EXT: JSON message + requestId
EXT->>Page: navigate
Page-->>EXT: loaded
EXT-->>WS: messageResponse { result }
WS-->>MCP: success
MCP->>WS: browser_snapshot
WS->>EXT: snapshot request
EXT-->>MCP: ARIA tree YAML
MCP-->>AI: text content + snapshot
```
### 组件职责
| 模块 | 角色 |
|--------|------|
| `src/index.ts` | CLI入口点，工具注册，生命周期 |
| `src/server.ts` | MCP协议处理程序（工具/资源） |
| `src/context.ts` | 到扩展程序的typed WebSocket RPC |
| `src/messaging/` | WebSocket上的请求/响应关联 |
| `src/tools/` | 浏览器自动化工具实现 |
| `src/persistence/` | 可选的Redis会话元数据存储 |
| `src/config/` | 环境驱动的配置 |
---
## 功能
| 功能 | 工具 |
|------------|-------|
| **导航** | `browser_navigate`, `browser_go_back`, `browser_go_forward`, `browser_wait` |
| **交互** | `browser_click`, `browser_hover`, `browser_type`, `browser_select_option`, `browser_drag`, `browser_press_key` |
| **检查** | `browser_snapshot`, `browser_screenshot`, `browser_get_console_logs` |
| **持久化** | 可选的Redis支持的会话和工具调用元数据 |
| **可观察性** | 结构化的stderr日志记录，支持可配置的日志级别 |
| **独立构建** | 无需私有monorepo依赖 |
---
## 要求
- **Node.js** 18或更高版本
- **Chrome** 且已安装[浏览器MCP扩展程序](https://browsermcp.io)
- **Redis** 6+（可选，用于会话持久化）
---
## 安装
### 从源代码
```bash
git clone https://github.com/BrowserMCP/mcp.git
cd mcp
npm install
npm run build
```
### MCP客户端配置
将以下内容添加到您的MCP客户端设置中（例如Cursor / Claude Desktop）：
```json
{
"mcpServers": {
"browsermcp": {
"command": "node",
"args": ["/absolute/path/to/mcp/dist/index.js"]
}
}
}
```
或者，在链接后使用已发布的二进制文件：
```bash
npm link
# command: mcp-server-browsermcp
```
### 连接扩展程序
1. 启动您的MCP客户端（它会启动此服务器）。
2. 打开Chrome并点击浏览器MCP扩展程序图标。
3. 点击目标标签页上的**Connect**。
4. 从您的AI助手调用工具。
---
## 配置
复制示例环境文件并调整值：
```bash
cp .env.example .env
```
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `WS_PORT` | `9009` | Chrome扩展程序的WebSocket端口 |
| `LOG_LEVEL` | `info` | 日志详细程度：`debug`，`info`，`warn`，`error` |
| `REDIS_ENABLED` | `false` | 启用Redis会话持久化 |
| `REDIS_HOST` | `127.0.0.1` | Redis主机名 |
| `REDIS_PORT` | `6379` | Redis端口 |
| `REDIS_PASSWORD` | _(empty)_ | Redis身份验证密码 |
| `REDIS_DB` | `0` | Redis数据库索引 |
| `REDIS_KEY_PREFIX` | `browsermcp:` | 键命名空间前缀 |
| `REDIS_CONNECT_TIMEOUT_MS` | `10000` | 连接超时 |
| `REDIS_MAX_RETRIES` | `10` | 重连尝试次数 |
| `REDIS_SESSION_TTL_SECONDS` | `86400` | 会话密钥TTL（24小时） |
启用Redis时，服务器记录连接事件、断开连接时间戳和工具调用计数 — 有助于调试和操作监控。
---
## 开发
```bash
# 安装依赖
npm install
# 监视模式
npm run dev
# 类型检查
npm run typecheck
# 校验
npm run lint
# 运行所有检查
npm run validate
```
### MCP检查工具
交互式调试工具模式和处理程序：
```bash
npm run build
npm run inspector
```
---
## 测试
```bash
# 运行所有测试
npm test
# 监视模式
npm run test:watch
```
测试涵盖环境解析、错误格式化、异步实用程序和Redis会话存储逻辑（使用模拟客户端）。
---
## 项目结构
```
mcp/
├── docs/
│ └── AUDIT.md # 工程审计笔记
├── src/
│ ├── config/ # 应用程序 + 环境配置
│ ├── messaging/ # WebSocket RPC层
│ ├── persistence/ # Redis连接 + 会话存储
│ ├── resources/ # MCP资源类型定义
│ ├── tools/ # 浏览器自动化工具
│ ├── types/ # 共享Zod模式和消息类型
│ ├── utils/ # 日志记录、错误处理、端口帮助程序
│ ├── context.ts # 扩展程序连接上下文
│ ├── index.ts # CLI入口点
│ ├── server.ts # MCP服务器工厂
│ └── ws.ts # WebSocket服务器生命周期
├── tests/ # Vitest单元测试
├── .env.example # 配置模板
├── eslint.config.js # ESLint扁平配置
├── tsup.config.ts # 构建配置
├── tsconfig.json # TypeScript（源代码）
├── tsconfig.test.json # TypeScript（测试 + 校验）
└── vitest.config.ts # 测试运行器配置
```
### 设计决策
- **仅stdio传输** — MCP客户端将服务器作为子进程启动；stdout保留用于协议。
- **stderr日志记录** — 所有诊断信息都发送到stderr，以避免破坏MCP消息。
- **可选Redis** — 持久化是可选的；服务器在没有Redis的情况下完全运行，适用于本地开发。
- **typed WebSocket RPC** — 每个扩展程序消息都是类型化的，从头到尾进行编译时安全性检查。
---
## 故障排除
### "无法连接到浏览器扩展程序"
Chrome扩展程序未连接。打开扩展程序弹出窗口并点击目标标签页上的**Connect**。
### 端口已被占用
另一个进程占用`WS_PORT`（默认为9009）。停止冲突的进程或设置不同的端口：
```bash
WS_PORT=9010 node dist/index.js
```
### Redis连接失败
如果启用了Redis但无法访问，服务器会记录错误并继续**无**持久化。验证Redis是否正在运行：
```bash
redis-cli ping
# PONG
```
### 工具返回超时错误
扩展程序在30秒内未响应。确保标签页处于活动状态且扩展程序已连接。使用`browser_wait`增加加载时间。
### MCP客户端显示无工具
确认您的MCP配置中的服务器二进制路径是绝对路径，并且`npm run build`成功完成。
---
## 贡献
1. 分叉仓库并创建功能分支。
2. 安装依赖项：`npm install`
3. 进行更改并测试：`npm run validate`
4. 提交拉取请求并附上清晰的描述和测试计划。
### 提交指南
- 每个提交一个逻辑更改。
- 使用约定前缀：`feat:`，`fix:`，`refactor:`，`test:`，`docs:`，`chore:`。
- 在推送之前运行`npm run validate`。
---
## 常见问题
**这会启动新的浏览器吗？**
否。它通过扩展程序控制现有的Chrome配置文件。
**我的数据会发送到远程服务器吗？**
自动化在本地运行。数据仅在您的AI客户端、此服务器和您的浏览器之间流动。
**我需要Redis吗？**
否。Redis是可选的，默认情况下禁用。
**支持哪些浏览器？**
Chrome和基于Chromium的浏览器，安装了浏览器MCP扩展程序。
**这与Playwright MCP有何不同？**
Playwright MCP启动浏览器实例。浏览器MCP使用Chrome扩展程序从您的登录配置文件中减少CAPTCHA和登录摩擦。
**多个扩展程序可以连接吗？**
一次只能激活一个WebSocket连接。新连接会替换前一个连接。
---
## 许可证
Apache License 2.0 — 请参阅[LICENSE](LICENSE)。
改编自具有配置文件重用和隐身自动化的浏览器扩展程序架构的[Playwright MCP服务器](https://github.com/microsoft/playwright-mcp)。
