Chrome Debug MCP

🚀 Chrome Debug MCP 服务器

Chrome Debug MCP 服务器是一个基于调试协议的浏览器自动化工具，它借助 Chrome 的调试端口，能够连接到已有的 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 Client ←→ stdio ←→ MCP Server ←→ Chrome Debug Port ←→ Chrome Browser

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

开发与调试

# 监听模式编译
npm run dev

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

发布到 npm

# 构建项目
npm run build

# 发布到 npm
npm publish

致谢

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

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

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

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

📄 许可证

本项目采用 MIT 许可证。

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