MCP Browser Agent

想象一下，你的AI助手Claude不再只是一个被限制在对话框里的“大脑”，而是能伸出双手，像真人一样打开浏览器、点击链接、填写表单、甚至直接调用API接口。这正是 mcp-browser-agent 带来的革命性体验。它作为一座桥梁，通过模型上下文协议，将Claude Desktop与强大的Playwright浏览器自动化引擎连接起来，赋予了AI真正的自主网络交互能力。

项目基本信息

一、项目介绍

MCP Browser Agent 是一个专门为 Claude Desktop 设计的 MCP 集成。与那些提供通用浏览器控制的工具不同，它的目标非常明确：让 Claude 成为一个能够自主规划和执行浏览器任务的智能代理。

它的核心能力可以归纳为三个方面：

1. 高级浏览器自动化：通过集成 Playwright，Agent 能够导航到任意 URL、捕获全屏或元素截图、执行精确的 DOM 交互（点击、填写、选择、悬停），并在浏览器上下文中执行任意 JavaScript 代码。
2. 强大的 API 客户端：除了操控浏览器，Agent 还能直接发起 HTTP 请求（支持 GET、POST、PUT、PATCH、DELETE），配置请求头与消息体，并处理响应数据。
3. MCP 资源管理：Agent 会将浏览器控制台日志和截图作为 MCP 资源暴露出来，方便 Claude 在任务执行过程中进行查询和参考，形成一个闭环。

项目在技术实现上由四个核心模块构成：index.ts (服务器初始化)、tools.ts (工具定义与注册)、handlers.ts (请求路由) 和 executor.ts (功能执行)。这种清晰的模块化设计使得其逻辑易于理解和扩展。

二、核心优势

专为 Claude Desktop 深度优化

不同于某些追求“大而全”的通用 MCP 服务器，MCP Browser Agent 的设计和测试紧密围绕 Claude Desktop 进行。这意味着它的工具描述、交互模式和错误反馈都针对 Claude 的理解和决策方式进行了调优，使用起来更加流畅和自然。

真正的代理能力

该项目并非简单的工具集合，而是一个具备代理特性的系统。它通过以下设计体现其“代理”属性：

• 持久化状态：在多个命令之间保持同一个浏览器会话，Claude 可以执行一连串相关的操作，如同在处理一个完整的工作流。
• 智能错误恢复：当操作失败时，Agent 会提供详细的错误信息，帮助 Claude 理解问题并尝试调整策略，而非简单中断。
• 丰富的上下文反馈：通过捕获控制台日志和保存截图，Claude 能更好地“理解”网页上发生了什么，从而做出更准确的下一步决策。

灵活性与可配置性

项目提供了多种配置浏览器的方式。你可以通过修改 Claude Desktop 的配置文件、创建 ~/.mcp_browser_agent_config.json 文件、设置环境变量或传递命令行参数，来轻松指定使用 Chrome、Firefox、Edge 或 WebKit。

三、适用场景

自动化 Web 测试与表单填写

你可以让 Claude 自动完成一系列回归测试步骤，例如：“打开登录页面，使用 testuser 和 pass123 登录，然后导航到‘个人设置’页面，将语言修改为‘中文’，最后截图保存。” Claude 会一步步拆解指令并调用相应工具完成操作。

网页数据抓取与监控

对于没有公开 API 的网站，可以指挥 Claude 进行数据采集。比如：“去 Hacker News 首页，把排名前 10 的新闻标题和链接整理成一个表格。” Claude 会导航、等待页面加载、执行 JavaScript 提取数据，并返回结构化结果。

辅助前端开发与调试

在开发过程中，你可以让 Claude 帮你快速验证功能。例如：“在当前开发环境打开的页面（http://localhost:3000）中，点击‘提交’按钮，然后把控制台里的报错信息发给我。” 这省去了你手动切换窗口、点击、查看控制台的繁琐过程。

API 探索与集成

利用其内置的 API 工具，Claude 可以充当一个智能的 API 客户端。你可以指示它：“调用 https://api.example.com/users 这个接口，获取用户列表，并从中找出所有管理员用户。”

四、安装教程

环境要求

详细安装步骤

1. 克隆项目到本地

   git clone https://github.com/imprvhub/mcp-browser-agent.git
   cd mcp-browser-agent

2. 安装项目依赖

   npm install

   这个命令会安装所有必需的包，包括 Playwright。首次运行时，Playwright 会自动下载所需的浏览器驱动（Chromium, Firefox, WebKit）。

3. 构建项目

   npm run build

4. 配置 Claude Desktop
   这是连接 Claude 和 Browser Agent 的关键一步。你需要编辑 Claude Desktop 的配置文件，其位置取决于你的操作系统：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   如果文件不存在，请创建它。然后，将以下内容添加到配置文件中。请注意将 ABSOLUTE_PATH_TO_DIRECTORY 替换为你的实际项目路径。

   {
     "mcpServers": {
       "browserAgent": {
         "command": "node",
         "args": [
           "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
           "--browser",
           "chrome"
         ]
       }
     }
   }

   • 路径示例 (macOS/Linux): /Users/your_username/Documents/mcp-browser-agent
   • 路径示例 (Windows): C:\\Users\\your_username\\Projects\\mcp-browser-agent （注意双反斜杠）
5. 启动 Claude Desktop
   完全退出并重新启动 Claude Desktop。如果配置正确，Claude 启动后，MCP Browser Agent 服务会在后台自动运行。你也可以在终端中手动运行 node dist/index.js 来启动服务进行测试。

五、使用示例

配置成功后，你就可以在 Claude Desktop 中通过自然语言下达指令了。

示例一：基础导航与截图

用户: 导航到 https://www.google.com，然后给首页截个图，命名为 google-homepage。

Claude 的操作:
Claude 会理解你的意图，并调用 MCP Browser Agent 的 browser_navigate 工具，然后紧接着调用 browser_screenshot 工具。

示例二：表单填写与提交

用户: 去 https://the-internet.herokuapp.com/login 这个网站，用 tomsmith 和 SuperSecretPassword! 登录，最后告诉我是否登录成功。

Claude 的操作:
Claude 将执行一个多步骤流程：

1. browser_navigate 到登录页。
2. browser_fill 填写用户名和密码字段。
3. browser_click 点击登录按钮。
4. 根据导航后的页面快照或标题，判断并回复你是否登录成功。

示例三：执行 JavaScript 并返回数据

用户: 打开 https://example.com，然后执行一段脚本，告诉我这个页面有多少个链接。

Claude 的操作:
Claude 会调用 browser_navigate，然后使用 browser_evaluate 工具，执行类似 document.querySelectorAll('a').length 的 JavaScript 代码，并直接返回结果数字。

示例四：链式 API 调用

用户: 先调用 https://jsonplaceholder.typicode.com/users/1 获取用户信息，再根据返回的用户 ID，去调用 https://jsonplaceholder.typicode.com/posts?userId=1 获取这个用户的所有帖子。

Claude 的操作:
Claude 将展现其代理规划能力：

1. 调用 api_get 获取用户信息。
2. 分析返回的 JSON 数据，提取出 id 字段。
3. 将提取出的 id 嵌入到第二个 API 的 URL 中，再次调用 api_get。
4. 整理并呈现用户的帖子列表。

六、常见问题

问：配置好后，Claude 提示“MCP Browser Agent: Server disconnected”怎么办？

答：这是最常见的问题，通常由以下原因引起：

1. 路径错误：请反复检查 claude_desktop_config.json 中 args 里的路径是否为绝对路径，并且确实指向 dist/index.js 文件。Windows 用户尤其注意使用双反斜杠 \\。
2. 依赖未安装或构建失败：请确保你已在项目根目录下成功运行 npm install 和 npm run build，并且没有报错。
3. 手动测试：打开终端，cd 到项目目录，运行 node dist/index.js。如果能正常启动并显示 Server started，说明服务器本身没问题，问题出在 Claude Desktop 的配置上。

问：浏览器启动了，但 Claude 找不到我描述的元素，或者点击没反应？

答：这是 Web 自动化中的经典挑战。可以尝试以下方法：

• 提供更精确的描述：使用元素上独特的文本、占位符或 aria-label。例如，“点击文字为‘Sign In’的按钮”。
• 等待时间：对于动态加载的页面，可能需要让 Claude 在操作前等待。可以使用 browser_evaluate 执行一个简单的 setTimeout 或等待某个特定元素的出现。
• 使用 browser_evaluate 作为后备：如果标准点击失效，可以让 Claude 使用 browser_evaluate 直接执行 JavaScript 来触发点击或检查元素状态。

问：我关闭了 Claude，但 Chrome 浏览器进程还在后台运行，怎么办？

答：这是基于 Chromium 的浏览器与 Playwright 交互时的一个已知问题。你需要手动结束进程：

• Windows: 打开任务管理器 (Ctrl+Shift+Esc)，找到 chrome.exe 或 chromium.exe 进程，结束任务。
• macOS: 打开“活动监视器”，搜索 chrome 或 chromium，选中并强制退出。
• Linux: 在终端中运行 ps aux | grep chrome 找到进程 ID (PID)，然后执行 kill <PID>。

七、总结

MCP Browser Agent 是连接 Claude Desktop 与真实 Web 世界的一把钥匙。它精心设计，旨在将 Claude 从一个被动的问答模型，升级为一个能主动探索、交互和操作的自主代理。通过清晰的结构、专为 Claude 优化的工具集以及对 API 交互的支持，它为 Web 自动化、测试、数据抓取和辅助开发开辟了全新的可能性。

尽管它依赖于 Playwright 生态，偶尔会受到浏览器进程管理等问题的影响，但其提供的强大功能和代理特性，使得它成为每一位希望深度挖掘 Claude 潜力的用户不可多得的利器。立即动手配置，亲身体验指挥 AI 畅游互联网的乐趣与高效吧。