铬调试-MCP

Name: 铬调试-MCP
Author: Rainmen-xia

作者：Rainmen-xia8 星标更新：2025-06-30

安装使用来源：spider==github.com

项目介绍

Chrome Debug MCP Server

语言: 英文 | 中文

这是一个通过调试协议实现Chrome浏览器自动化的Model Context Protocol (MCP)服务器，特别设计用于连接到Chrome调试端口，并启用具有持久登录会话的浏览器自动化。

🎯 项目优势

🚀 核心技术优势

🔧 零依赖部署
- 不需要Chrome扩展
- 不需要Chrome网络商店审批
- 在企业环境中完全自主
📦 容器友好
- 完美支持Docker/Kubernetes部署
- 没有扩展权限或安装问题
- 适合云原生架构

⚡ 两步启动

# 只需两个命令即可启动
# 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

🛡️ 企业级安全
- 基于标准的Chrome DevTools协议
- 不需要第三方扩展权限
- 完全本地操作

🚀 快速开始

方案1：直接使用（推荐）

无需安装，直接启动：

# 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连接失败

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

操作超时

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

截图失败

确认页面已完全加载
检查浏览器窗口大小设置
尝试刷新页面并重试操作

技术架构

MCP客户端 ←→ stdio ←→ 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

致谢

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

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

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

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

许可证

MIT许可证

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