Chrome Debug MCP

🚀 Chrome调试MCP服务器

这是一个用于Chrome浏览器自动化的模型上下文协议（MCP）服务器，它通过调试协议与Chrome调试端口建立连接，支持在保持登录会话的情况下实现浏览器自动化，为需要用户认证的自动化场景提供了理想解决方案。

🚀 快速开始

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

使用npx直接启动，无需安装：

# 1. 以调试模式启动Chrome
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# 2. 直接运行MCP服务器
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"]
    }
  }
}

就是这么简单！ 无需安装、下载，也无需复杂的路径配置。

💡 其他安装方法

全局安装：

npm install -g chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "chrome-debug-mcp"
    }
  }
}

本地项目安装：

npm install chrome-debug-mcp

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

💻 使用示例

基础用法

以下是一些可用工具的使用示例：

1. launch_browser

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

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

2. navigate_to

使用智能标签管理导航到指定URL。

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

3. click

在指定坐标处点击。

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

4. type_text

输入文本内容。

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

5. scroll_down / scroll_up

滚动页面。

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

6. hover

将鼠标悬停在指定位置。

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

7. resize_browser

调整浏览器窗口大小。

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

8. get_page_content

获取当前页面的HTML内容。

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

9. close_browser

关闭浏览器连接。

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

高级用法

典型用例

1. 社交媒体自动化

# 先在Chrome中手动登录Twitter/微博
# 然后使用MCP工具进行自动化操作
launch_browser -> navigate_to -> click -> type_text

2. 电商运营

# 保持淘宝/京东的登录状态
# 自动化产品搜索、价格监控等操作
launch_browser -> navigate_to -> type_text -> click

3. 数据抓取

# 从需要登录的网站抓取数据
# 绕过登录验证，直接进行操作
launch_browser -> navigate_to -> get_page_content

📚 详细文档

高级特性

智能标签管理

• 相同域名（如example.com）复用现有标签页。
• 不同域名自动创建新标签页。
• 避免重复打开相同网站。

自动等待机制

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

错误恢复

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

Docker环境支持

如果Chrome在Docker容器中运行：

# 在Docker中启动Chrome
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客户端 ←→ 标准输入输出 ←→ MCP服务器 ←→ Chrome调试端口 ←→ Chrome浏览器

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

开发与调试

# 监听模式编译
npm run dev

# 查看MCP通信日志
DEBUG=mcp* npm start

发布到npm

# 构建项目
npm run build

# 发布到npm
npm publish

📄 许可证

本项目采用MIT许可证。

致谢

本项目的设计理念和核心概念受到了RooCode项目的启发。RooCode是一个优秀的浏览器自动化MCP服务器实现，为我们提供了宝贵的技术参考和设计思路。

特别感谢RooCode团队在以下方面的贡献：

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

在此基础上，本项目进一步专注于保持登录会话的浏览器自动化，通过连接现有的Chrome调试端口来维护用户会话，实现了更实用的自动化功能。

核心优势

这个MCP服务器的最大特点是能够连接到现有的Chrome实例并保持登录会话，非常适合需要用户认证的自动化场景。通过Chrome调试端口，它可以接管已登录用户的浏览器会话，实现真正的“会话持久化”浏览器自动化。