page-agent MCP Server实战：让Claude Desktop和Copilot远程操控你的浏览器
【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent
page-agent MCP Server 是一个开箱即用的 Model Context Protocol（MCP）服务，它能让你正在使用的 AI 客户端（如 Claude Desktop、GitHub Copilot、Cursor）用一句自然语言驱动你自己的浏览器：自动填表、抓取数据、跨标签页执行多步任务。Page Agent 本体是一个运行在网页内的 GUI Agent，而 MCP Server 相当于给 AI 客户端开了一扇"操控浏览器"的后门——无需写一行自动化脚本。
一、3 个工具，看懂 MCP Server 的全部能力
MCP Server 对外只暴露了 3 个工具，职责清晰、上手零门槛 🧩：
| 工具名 | 输入 | 作用 |
|---|---|---|
execute_task | 一句自然语言任务描述 | 在浏览器中执行任务（阻塞式，完成后返回结果） |
get_status | 无 | 返回{ connected, busy }，查看 Hub 是否已连接、是否正忙 |
stop_task | 无 | 停止当前正在运行的任务 |
你只需要向 AI 客户端"提需求"，它会自动调用execute_task把任务转交给浏览器执行，并在结束后把结果文本带回来。
二、准备工作：3 步确认环境就绪
开始配置前，先确认这 3 个前提条件 ✅
- Node.js >= 20：MCP Server 通过
npx以纯 ESM 源码方式运行，没有构建步骤 - Page Agent Chrome 扩展：安装最新版 Page Agent Ext 到 Chrome，它是真正执行浏览器操作的一方
- 一个 OpenAI 兼容的 LLM API Key：Agent 的"大脑"，支持主流云端或本地部署模型
三、一键配置：Claude Desktop 连接 MCP Server 完整步骤
这是最常见的接入场景。打开 Claude Desktop 的配置文件（macOS 路径为~/Library/Application Support/Claude/claude_desktop_config.json），加入如下配置：
{ "mcpServers": { "page-agent": { "command": "npx", "args": ["-y", "@page-agent/mcp"], "env": { "LLM_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1", "LLM_API_KEY": "sk-xxx", "LLM_MODEL_NAME": "qwen3.5-plus" } } } }配置说明：
command+args：用npx -y @page-agent/mcp直接拉起 MCP Server，无需手动安装LLM_BASE_URL/LLM_API_KEY/LLM_MODEL_NAME：注入 Agent 使用的 LLM 配置（OpenAI 兼容协议）- 服务端口默认为
38401，如需修改可通过环境变量PORT覆盖
保存后重启 Claude Desktop 即可。
接入 Copilot / Cursor：同样一个配置
Copilot、Cursor 等客户端的 MCP 设置格式与 Claude Desktop 完全一致，把上面同一段 JSON 粘贴进对应客户端的 MCP 设置里就能用，一次配置，处处生效。
四、原理拆解：从 AI 指令到浏览器操作的完整链路
MCP Server 启动后会自动打开一个本地启动页（launcher），整个链路是"AI 客户端 → 本地服务 → 浏览器扩展"的三段式结构：
Claude / Copilot ⇄stdio/MCP⇄ @page-agent/mcp (Node.js) ⇄WebSocket⇄ Hub 页签（浏览器扩展） ⇅ HTTP Launcher 页（localhost:PORT）- AI 客户端通过 stdio 启动 MCP Server（
npx @page-agent/mcp） - MCP Server在
localhost上开启 HTTP + WebSocket 服务，并自动打开 launcher 页面 - launcher 页面检测扩展是否安装，若未安装会显示安装引导；已安装则触发扩展打开Hub 页签
- Hub 页签通过 WebSocket 连回 MCP Server，此后所有
execute_task都会被代理到 Hub，由扩展内的 MultiPage Agent 真正操作页面
安全设计：每一次远程操控都需你授权
Hub 侧的协议实现位于 hub-ws.ts：收到第一条外部消息时，浏览器会弹出确认框询问"是否允许外部应用通过 Page Agent 控制你的浏览器"。你可以在扩展设置中选择"允许所有 Hub 连接"（allowAllHubConnection），之后同一会话内不再重复打扰。任务执行也保证同一时间只跑一个，防止并发冲突。
五、实战场景：一句话能做什么
配置完成后，试试对 Claude Desktop 直接下指令 💬
- 数据提取："打开电商搜索页，查一下某品牌前 10 名商品的名称和价格，整理成表格给我"
- 表单批量操作："在 CRM 系统里把这 5 条工单状态改为'处理中'，每条改完确认一下"
- 跨标签页任务："在 A 标签页导出数据，然后在 B 标签页的报表页核对总数是否一致"
- 执行中想刹车：随时让 AI 调用
stop_task，或用get_status确认当前是否空闲
六、常见坑与快速排错
| 现象 | 原因与解法 |
|---|---|
报Port 38401 is in use | 另一个 MCP Server 实例还在运行，关掉它或换PORT环境变量 |
报Hub is not connected | 扩展未安装、版本过旧，或 Hub 页签被关掉了；重新打开 launcher 页刷新连接 |
报Agent is already running a task | Agent 正忙，等当前任务结束（或stop_task）再下发新任务 |
| launcher 显示"需要安装扩展" | 请从装有 Page Agent 扩展的浏览器打开该页面，安装后刷新 |
端口占用检测逻辑可参考 hub-bridge.js，launcher 页的完整源码在 launcher.html。
七、核心源码导读
想深入理解实现，按这条路径阅读效率最高 📚
- MCP 入口与工具注册：index.js —— 3 个 MCP 工具的完整定义
- HTTP + WebSocket 桥接：hub-bridge.js —— HubBridge 类，负责与 Hub 页签的双向通信
- 扩展侧 Hub 协议：hub-ws.ts —— 消息格式（
execute/stop/result/error）与用户授权逻辑 - MCP 模块文档：packages/mcp/README.md —— 含完整架构图与环境变量说明
- 扩展 API 文档：extension_api.md
整体架构采用纯 JS ESM、零构建步骤的设计，源码即发布产物，阅读和维护都非常友好。
写在最后
page-agent MCP Server 把"自然语言 → 浏览器操作"这条链路压缩到了最短：AI 客户端说一句，浏览器就动手。它目前是 Beta 特性，但三个工具、一条链路、一处授权的设计，已经足以支撑日常自动化、数据提取和跨页任务等高频场景。装上扩展、贴上配置，你的 Claude Desktop 就多了"双手"。
【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
