chrome-debug-mcp

你是否曾经为了调试一个复杂的网页而焦头烂额？是否希望有一个智能助手能帮你自动操作浏览器、注入脚本、拦截请求，甚至帮你分析页面错误？今天要介绍的开源项目 chrome-debug-mcp，正是为了解决这些痛点而生。它像是一个桥梁，把大型语言模型（LLM）的能力和Chrome浏览器的调试控制权连接在了一起，让AI能够像一位经验丰富的开发工程师一样，帮你操作和调试网页。

项目基本信息

一、项目介绍

chrome-debug-mcp 是一个实现了模型上下文协议（Model Context Protocol，MCP）的服务器。简单来说，它允许你通过像Roo Code（原Claude Dev）这样的AI编程助手，直接控制Chrome浏览器。你可以让AI帮你启动浏览器、点击按钮、填写表单、注入用户脚本，甚至拦截和修改网络请求。

这个项目的核心是将强大的浏览器自动化工具Playwright（以及部分Puppeteer能力）与MCP协议结合起来，并特别加入了完整的Greasemonkey API支持。这意味着，你不仅可以完成常规的网页自动化操作，还能像在浏览器扩展中一样，使用 GM_setValue、GM_xmlhttpRequest 等熟悉的函数，实现跨域请求和本地数据存储。

二、核心优势

开源免费

项目采用MIT开源协议，代码完全公开。你可以自由地将它集成到自己的项目中，也可以根据需要进行二次开发和修改，无需担心版权或许可费用问题。

社区支持

虽然这是一个相对较新的项目，但已经吸引了开发者的关注（GitHub上已有44颗星和5次复刻）。作者robertheadley保持着积极的更新频率，问题响应及时，社区氛围良好。

持续更新

从GitHub的提交记录来看，项目在持续演进中。最近的一次更新就在2026年3月，说明它不是一个被废弃的实验品，而是一个活跃维护的工具。

功能丰富且独特

与普通的浏览器自动化工具不同，chrome-debug-mcp是专为LLM设计的。它通过MCP协议，让AI助手能够以结构化的方式调用浏览器功能，并获取反馈。它还特别支持加载未打包的Chrome扩展，并可以关闭Chrome的“自动化控制”提示条，这使得自动化行为更加真实、隐蔽。

三、适用场景

开发者学习和参考

对于想学习浏览器自动化、MCP协议或Playwright库的开发者来说，这是一个极佳的范例项目。它的代码结构清晰，你可以看到如何将Node.js程序封装成一个MCP服务器。

个人项目使用和集成

如果你正在开发一个需要与网页大量交互的AI应用（例如自动填表工具、数据采集机器人、前端自动化测试脚本），那么chrome-debug-mcp可以作为完美的底层驱动。你只需要编写简单的指令，AI就能帮你操作浏览器。

企业级应用开发

在企业环境中，自动化测试、网页监控、数据抓取是常见需求。通过集成chrome-debug-mcp，可以构建出更智能、更稳定的自动化流程。例如，当页面布局发生变化时，基于LLM的选择器生成逻辑可能比固定的CSS选择器更具适应性。

日常工作和效率提升

对于非程序员来说，这个工具也有巨大的潜力。想象一下，你可以用自然语言告诉AI：“帮我登录公司内部系统，下载上个月的销售报表，并保存为PDF。”如果有了chrome-debug-mcp的支持，这样的愿景将触手可及。

四、安装教程

系统要求

详细安装步骤

第一步：安装Roo Code扩展

打开Visual Studio Code，点击左侧活动栏的“扩展”图标（或按快捷键Ctrl+Shift+X），在搜索框中输入“Roo Code”，找到后点击“安装”。这个扩展将是您与chrome-debug-mcp服务器交互的主要界面。

第二步：克隆项目到本地

打开终端（Terminal），执行以下命令将项目代码下载到您的电脑上：

git clone https://github.com/robertheadley/chrome-debug-mcp.git

第三步：进入项目目录并安装依赖

cd chrome-debug-mcp
npm install

第四步：构建项目

npm run build

这一步会将TypeScript代码编译成JavaScript，生成可在Node.js中直接运行的build/index.js文件。

第五步：配置Roo Code

找到Roo Code的配置文件cline_mcp_settings.json。通常它位于用户目录下的roo-code文件夹中，或者你可以通过Roo Code的设置界面找到“编辑MCP设置”的入口。添加以下配置：

{
  "mcpServers": {
    "chrome-debug": {
      "command": "node",
      "args": ["你的实际路径/chrome-debug-mcp/build/index.js"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

注意：请将你的实际路径替换为你在第二步中克隆项目到本地的绝对路径。

五、使用示例

在Roo Code中配置好MCP服务器后，你就可以在对话中直接使用它提供的各种工具（Tools）了。下面是一些典型的使用案例。

基础操作：启动浏览器并打开网页

你可以对AI说：“启动Chrome浏览器，并打开百度”，Roo Code会自动调用以下工具：

use_mcp_tool({
  server_name: "chrome-debug",
  tool_name: "launch_chrome",
  arguments: {
    executablePath: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
    url: "https://www.baidu.com"
  }
})

页面交互：搜索关键词

假设浏览器已经打开，你可以让AI在百度搜索框中输入“MCP协议”：

use_mcp_tool({
  server_name: "chrome-debug",
  tool_name: "type",
  arguments: {
    selector: "#kw",
    text: "MCP协议",
    delay: 100
  }
})

然后点击“百度一下”按钮：

use_mcp_tool({
  server_name: "chrome-debug",
  tool_name: "click",
  arguments: {
    selector: "#su",
    delay: 500
  }
})

注入用户脚本：改变页面背景色

你可以将一个包含Greasemonkey API的用户脚本注入到页面中。首先创建一个名为change-bg.js的文件，内容如下：

// ==UserScript==
// @name         Change Background
// @namespace    http://tampermonkey.net/
// @version      0.1
// @description  Change page background to light blue
// @author       You
// @match        *://*/*
// @grant        GM_addStyle
// ==/UserScript==

GM_addStyle('body { background-color: lightblue !important; }');
console.log('User script injected successfully!');

然后通过工具加载这个脚本：

use_mcp_tool({
  server_name: "chrome-debug",
  tool_name: "launch_chrome",
  arguments: {
    url: "https://www.baidu.com",
    userscriptPath: "/绝对路径/change-bg.js"
  }
})

高级调试：捕获控制台日志

当页面运行出错时，你可以让AI帮你获取控制台的所有输出：

use_mcp_tool({
  server_name: "chrome-debug",
  tool_name: "get_console_logs",
  arguments: {
    clear: true  // 获取后清除日志，避免重复
  }
})

多标签页管理

你可以同时管理多个标签页，例如打开一个新标签页并切换过去：

// 列出所有标签页
use_mcp_tool({
  server_name: "chrome-debug",
  tool_name: "list_tabs",
  arguments: {}
})

// 打开新标签页
use_mcp_tool({
  server_name: "chrome-debug",
  tool_name: "new_tab",
  arguments: {
    url: "https://github.com"
  }
})

// 切换回第一个标签页（索引从0开始）
use_mcp_tool({
  server_name: "chrome-debug",
  tool_name: "switch_tab",
  arguments: {
    tabId: "从list_tabs返回的ID"
  }
})

六、常见问题

问题1：启动Chrome时报错“无法连接到浏览器”

解决方案：这通常是因为Chrome没有正常启动或者调试端口被占用。请确保你的系统中已经安装了Chrome浏览器，并且没有其他程序占用9222端口（Chrome DevTools Protocol的默认端口）。你也可以尝试在launch_chrome工具中显式指定executablePath参数，指向Chrome的正确安装路径。

问题2：Roo Code提示找不到chrome-debug服务器

解决方案：请仔细检查cline_mcp_settings.json文件中的args路径是否正确，并且使用了绝对路径。同时确认你已经运行过npm run build命令，确保build/index.js文件存在。修改配置文件后，需要重启VS Code或重新加载窗口。

问题3：注入的用户脚本不生效

解决方案：首先检查脚本语法是否正确，特别是@match规则是否匹配当前页面的URL。其次，确保在launch_chrome工具中正确指定了userscriptPath参数。最后，可以通过get_console_logs工具查看控制台是否有脚本报错信息。

问题4：使用GM_xmlhttpRequest遇到跨域问题

解决方案：GM_xmlhttpRequest本身就是用来解决跨域问题的。如果仍然失败，请检查请求的URL是否正确，以及目标服务器是否支持你使用的请求方法（如GET、POST）。另外，注意某些网站可能有严格的反爬机制，会拒绝来自自动化工具的请求。

七、总结

chrome-debug-mcp 是一个富有想象力的项目，它巧妙地结合了浏览器自动化、LLM和MCP协议，为智能网页交互开辟了新的可能性。虽然它目前还存在一些不足，比如文档尚不完善、对新手不够友好，但它的核心价值是毋庸置疑的。

对于开发者来说，这是一个值得投入时间学习和研究的工具。你可以用它来构建下一代AI驱动的自动化测试框架、智能爬虫，或者仅仅是作为日常调试的得力助手。

如果你对浏览器自动化、AI Agent或提升开发效率感兴趣，我非常推荐你尝试一下chrome-debug-mcp。 安装它，体验一下用自然语言指挥浏览器工作的感觉，或许会给你带来意想不到的惊喜。