Brower Control MCP

浏览器MCP

浏览器MCP是一个MCP（模型上下文协议）服务器+Chrome扩展程序，允许您使用VS Code、Claude、Cursor和Windsurf等AI应用程序自动化浏览器。

特性

⚡ 快速：自动化在您的机器上本地进行，从而在没有网络延迟的情况下获得更好的性能。

🔒 私人：由于自动化发生在本地，您的浏览器活动将保留在设备上，不会发送到远程服务器。

👤 登入：使用您现有的浏览器配置文件，保持您登录所有服务。

🥷🏼 隐形：通过使用真实的浏览器指纹来避免基本的机器人检测和验证码。

建筑

该项目由两部分组成：

1. MCP服务器 （此存储库）：通过模型上下文协议提供浏览器自动化工具
2. Chrome 扩展 （必填）：通过WebSocket将浏览器连接到MCP服务器

服务器通过本地WebSocket连接（默认端口：9003）与Chrome扩展程序通信，确保所有自动化都发生在您的本地计算机上，而不会将数据发送到外部服务器。

快速开始

1.安装依赖关系并构建

npm install
npm run build

2.安装Chrome扩展程序

1. 打开Chrome浏览器并导航到 chrome://extensions/
2. 启用“开发人员模式”（在右上角切换）
3. 点击“加载解包”
4. 选择 extension 此存储库中的目录
5. 将扩展固定到工具栏（可选但推荐）

3.启动MCP服务器

npm run dev

服务器将启动并等待浏览器扩展连接。

4.连接分机

1. 在Chrome中单击浏览器MCP扩展程序图标
2. 扩展应自动连接到服务器
3. 您应该看到带有绿色徽章的“已连接”状态

5.配置克劳德桌面

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/absolute/path/to/brower-control-mcp/dist/index.js"]
    }
  }
}

替换 /absolute/path/to/brower-control-mcp/dist/index.js 你的实际路径。

6.重新启动克劳德桌面

重新启动Claude Desktop以加载MCP服务器。现在，您可以让Claude自动化您的浏览器！

详细文件

• 使用指南 -完整的设置和配置说明
• 扩展指南 -Chrome扩展程序文档

用法

运行服务器

npm run dev

或者在建造之后：

node dist/index.js

Claude桌面配置

将此添加到您的Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/absolute/path/to/brower-control-mcp/dist/index.js"]
    }
  }
}

Chrome 扩展

附带的Chrome扩展程序将您的浏览器连接到MCP服务器：

• 位置: extension/ 此存储库中的目录
• 安装：在Chrome中作为解压缩的扩展程序加载（请参阅快速入门）
• 连接：自动连接到 ws://localhost:9003
• 状态：单击扩展图标检查连接状态

看 扩展名/README.md 详细文档。

可用工具

导航工具

• 导航：导航到URL
• go返回：返回浏览器历史记录
• goForward：在浏览器历史记录中前进

交互工具

• 点击：通过CSS选择器或ARIA标签单击元素
• 悬停：将鼠标悬停在元素上
• 类型：在输入元素中键入文本
• select选项：在下拉列表中选择一个选项
• 拖拽：将一个元素拖动到另一个元素

检测工具

• 快照：使用ARIA快照捕获当前页面状态
• 截图：截取当前页面的屏幕截图
• getConsoleLogs：检索浏览器控制台日志

实用工具

• 等待：等待指定的秒数
• 按键：按键盘键（例如Enter、Escape、ArrowDown）

发展

项目结构

src/
├── index.ts              # Main entry point
├── server.ts             # MCP server setup
├── context.ts            # WebSocket connection manager
├── ws.ts                 # WebSocket server creation
├── tools/
│   ├── tool.ts          # Tool type definitions
│   ├── common.ts        # Navigation tools
│   ├── custom.ts        # Screenshot and console tools
│   └── snapshot.ts      # Interaction tools
├── resources/
│   └── resource.ts      # Resource type definitions
└── utils/
    ├── port.ts          # Port management utilities
    └── snapshot.ts      # ARIA snapshot capture

构建和开发脚本

• npm run build：构建项目
• npm run watch：观看模式用于开发
• npm run typecheck：无建筑类型检查
• npm run dev：构建并运行服务器
• npm run inspector：运行MCP检查器进行调试

运作原理

1. MCP服务器启动并在端口9003上创建WebSocket服务器
2. Chrome扩展程序连接到WebSocket服务器
3. AI应用程序（Claude、VS Code等）通过stdio与MCP服务器通信
4. 当调用工具时，MCP服务器通过WebSocket向浏览器发送命令
5. 扩展程序在实际浏览器中执行命令
6. 捕获结果（ARIA快照、屏幕截图等）并返回给AI

该架构确保：

• 本地执行：一切都在你的机器上运行
• 真实浏览器：将您的实际Chrome个人资料用于所有登录
• 隐私：没有数据离开您的设备
• 隐形：真正的浏览器指纹，而不是无头自动化工具

协议消息

服务器通过WebSocket使用JSON消息与浏览器扩展进行通信：

请求格式

{
  "type": "browser_click",
  "selector": "#submit-button"
}

响应格式

{
  "type": "browser_click_response",
  "data": { "snapshot": "..." },
  "error": null
}

支持的消息类型

• browser_navigate / browser_navigate_response
• browser_go_back / browser_go_back_response
• browser_go_forward / browser_go_forward_response
• browser_click / browser_click_response
• browser_hover / browser_hover_response
• browser_type / browser_type_response
• browser_select_option / browser_select_option_response
• browser_drag / browser_drag_response
• browser_press_key / browser_press_key_response
• browser_screenshot / browser_screenshot_response
• browser_get_console_logs / browser_get_console_logs_response
• browser_capture_snapshot / browser_capture_snapshot_response

安全与隐私

• 所有自动化都在您的机器上本地进行
• 没有数据发送到外部服务器
• WebSocket连接仅限于本地（127.0.0.1）
• 使用您现有的浏览器配置文件和凭据
• 完全控制AI可以访问的内容

故障排除

“未连接到浏览器扩展”错误

确保：

1. Chrome扩展程序已安装并启用
2. 扩展已连接（检查扩展图标）
3. MCP服务器正在运行
4. 没有防火墙阻止端口9003

端口已在使用中

启动时，服务器会自动终止使用端口9003的任何进程。如果您发现问题：

• 检查是否有其他实例正在运行
• 尝试在中更改端口 src/ws.ts

鸣谢

该项目改编自微软的Playwright MCP服务器，重新聚焦于自动化现有的用户浏览器，而不是创建新的自动化实例。

许可证

麻省理工学院