Chrome Debug MCP (chrome-debug-mcp)

Chrome调试MCP服务器

语言: 英语 | 中文

通过调试协议实现Chrome浏览器自动化的模型上下文协议（MCP）服务器，专门设计用于连接到Chrome调试端口，并通过持久登录会话实现浏览器自动化。

🎯 项目优势

🚀 核心技术优势

1. 🔧 零依赖部署

- 无需Chrome扩展程序 - 无需Chrome网上商店批准 - 在企业环境中完全自主

1. 📦 集装箱友好

- 对Docker/Kubernetes部署的完美支持 - 没有扩展权限或安装问题 - 非常适合云原生架构

1. ⚡ 两步启动

   # Launch with just two commands
   # 1. Start Chrome in debug mode
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
   # 2. Run MCP server
   npx chrome-debug-mcp

1. 🛡️ 企业级安全

- 基于标准Chrome DevTools协议 - 无需第三方扩展权限 - 完成本地操作

🚀 快速开始

选项1：直接使用（推荐）

使用npx启动-无需安装：

# 1. Start Chrome in debug mode
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# 2. Run MCP server directly
npx chrome-debug-mcp

方案2：地方发展

git clone https://github.com/rainmenxia/chrome-debug-mcp.git
cd chrome-debug-mcp
npm install
npm run build
npm start

核心功能

• ✅ Chrome调试端口连接：基于标准Chrome DevTools协议，无需扩展
• 🏢 企业级部署：零依赖部署，无需Chrome网上商店批准
• 📱 智能选项卡管理：重复使用相同域的选项卡，避免重复打开
• 🖼️ 实时截图反馈：每次操作后自动截图以获得视觉反馈
• 🌐 网络活动监控：自动等待页面加载完成
• 🐳 原生Docker支持：完美支持容器化Chrome实例，无扩展限制
• ⚡ 两步启动：在调试模式下启动Chrome，然后运行 npx chrome-debug-mcp，无需复杂的安装
• 🔍 智能浏览器发现：在本地和Docker环境中自动发现Chrome实例

配置和使用

1.启动Chrome调试模式（必填）

服务器需要连接到启用调试端口的Chrome实例：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir=c:\temp\chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

重要提示:

• --user-data-dir 参数指向一个临时目录，确保Chrome在调试模式下启动
• 启动后，您可以正常登录网站，登录会话将被保留
• 服务器将重用此Chrome实例，无需重新登录

2.配置MCP客户端

将以下配置添加到MCP客户端：

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

就是这样！ 无需安装、下载，也不需要复杂的路径配置。

💡 替代安装方法: 全球安装: ``bash npm install -g chrome-debug-mcp ` `json { "mcpServers": { "browser-automation": { "command": "chrome-debug-mcp" } } } ` **本地项目安装**: `bash npm install chrome-debug-mcp ` `json { "mcpServers": { "browser-automation": { "command": "npx", "args": ["chrome-debug-mcp"] } } } ``

可用工具

1.启动浏览器

连接到Chrome调试端口并初始化浏览器会话。

{
  "name": "launch_browser",
  "arguments": {
    "remote_host": "http://localhost:9222"  // optional
  }
}

2.navigate_to

使用智能选项卡管理导航到指定的URL。

{
  "name": "navigate_to", 
  "arguments": {
    "url": "https://example.com"
  }
}

3.点击

在指定坐标处单击。

{
  "name": "click",
  "arguments": {
    "coordinate": "100,200"
  }
}

4.类型文本

输入文本内容。

{
  "name": "type_text",
  "arguments": {
    "text": "Hello World"
  }
}

5.scroll_down/scroll_up

滚动页面。

{
  "name": "scroll_down",
  "arguments": {}
}

6.悬停

将鼠标悬停在指定位置。

{
  "name": "hover",
  "arguments": {
    "coordinate": "100,200"
  }
}

7.调整浏览器大小

调整浏览器窗口大小。

{
  "name": "resize_browser",
  "arguments": {
    "size": "1200,800"
  }
}

8.获取页面内容

获取当前页面的HTML内容。

{
  "name": "get_page_content",
  "arguments": {}
}

9.关闭浏览器

关闭浏览器连接。

{
  "name": "close_browser",
  "arguments": {}
}

典型使用案例

1.社交媒体自动化

# Manually log into Twitter/Weibo in Chrome first
# Then use MCP tools for automation
launch_browser -> navigate_to -> click -> type_text

2.电子商务运营

# Keep logged-in state for Taobao/JD
# Automate product search, price monitoring, etc.
launch_browser -> navigate_to -> type_text -> click

3.数据报废

# Scrape data from login-required websites
# Bypass login verification, direct operations
launch_browser -> navigate_to -> get_page_content

高级功能

智能选项卡管理

• 相同的域（例如。， example.com)重用现有选项卡
• 不同的域会自动创建新选项卡
• 避免重复打开同一网站

自动等待机制

• 监控网络活动，等待页面加载完成
• HTML内容稳定性检测
• 动态内容加载的自动处理

错误恢复

• 连接中断时自动重新连接
• 缓存成功的连接端点
• 详细的错误日志和反馈

Docker环境支持

如果Chrome在Docker容器中运行：

# Start Chrome in Docker
docker run -d --name chrome-debug \
  -p 9222:9222 \
  --shm-size=2gb \
  zenika/alpine-chrome \
  --no-sandbox \
  --disable-dev-shm-usage \
  --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9222

服务器将自动发现Docker环境中的Chrome实例。

故障排除

Chrome连接失败

1. 确认Chrome已启动 --remote-debugging-port=9222
2. 检查端口9222是否被占用： lsof -i :9222
3. 确保没有其他Chrome实例正在运行

操作超时

1. 检查网络连接
2. 增加页面加载超时时间
3. 确认目标网站可访问

截图失败

1. 确认页面已完全加载
2. 检查浏览器窗口大小设置
3. 尝试刷新页面，然后重试操作

技术架构

MCP Client ←→ stdio ←→ MCP Server ←→ Chrome Debug Port ←→ Chrome Browser

• 传输协议：stdio（标准输入/输出）
• 浏览器引擎：Puppeteer+Chrome DevTools协议
• 连接方式：WebSocket（Chrome调试端口）
• 图像格式：WebP/PNG base64编码

开发与调试

# Watch mode compilation
npm run dev

# View MCP communication logs
DEBUG=mcp* npm start

发布到npm

# Build project
npm run build

# Publish to npm
npm publish

致谢

该项目的设计理念和核心概念受到了 房间代码 项目。RooCode是一个优秀的浏览器自动化MCP服务器实现，提供了宝贵的技术参考和设计见解。

特别感谢RooCode团队在以下领域做出的贡献：

• 🎯 MCP协议集成：提供将MCP服务器与浏览器自动化相结合的技术解决方案
• 🔗 浏览器连接：演示了优雅的浏览器连接和会话管理
• 📋 工具API设计：为规范浏览器操作提供了参考框架

在RooCode的基础上，该项目进一步关注 具有持久登录会话的浏览器自动化，通过连接到现有的Chrome调试端口来维护用户会话，实现更实用的自动化功能。

许可证

MIT许可证

______________________________________________________________________

核心优势：此MCP服务器的最大特点是能够连接到现有的Chrome实例并维护登录会话，这使其成为需要用户身份验证的自动化场景的理想选择。通过Chrome调试端口，它可以接管用户记录的浏览器会话，实现真正的“会话持久化”浏览器自动化。