@mearl/mcp-server

Mearl MCP Server

让 AI 能够与浏览器实时交互的 MCP 服务器。

功能

• 📊 browser_get_requests: 获取历史请求记录
• 📊 browser_get_events: 获取指定标签页的 RUM/aplus/ARMS 埋点事件，无需打开 DevTools panel
• 📝 browser_get_logs: 获取控制台日志
• 🎭 browser_set_mock: 动态设置 Mock 数据
• 🌐 browser_list: 统一列出普通浏览器和托管浏览器，返回默认目标、类型及连接状态
• 📴 browser_release: 按用户明确要求释放 debugger/CDP 控制和会话级临时效果，并保留浏览器与全部标签页
• 🚀 browser_launch / browser_close: 启动或关闭独立 Profile 的托管 Chrome
• 🌐 browser_page_snapshot: 首次获取页面结构和可交互元素
• ⚡ browser_page_click/type/hover/scroll/press/upload: 执行页面动作，默认内置观察，返回通知、可交互控件、焦点、导航或直接打开的新标签页

浏览器交互工作流

首次进入页面时调用 browser_page_snapshot 建立结构基线。后续点击、输入、悬停、滚动、按键和上传直接调用 browser_page_click/type/hover/scroll/press/upload，它们默认内置观察，动作与异步同步在一次调用内完成；同页结果读取 effects.notifications、effects.interactives 和 effects.focus。新增或变化的可交互节点会尽量携带可直接用于后续动作的 node.ref，解析不到 ref 时回退使用 node.selector。导航结果读取新 URL 和就绪状态；动作直接打开新标签页时，openedTabs 返回可继续操作的 tabId，无需调用 browser_tab_list。通常仅在导航后、fullSnapshotRecommended: true 或需要视觉判断时重新 snapshot 或截图；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。browser_page_eval 默认裸执行，仅在表达式会修改页面且需要变化信号时显式传 observe 对象。

长列表重新感知时优先使用 browser_page_snapshot(mode: "viewport")；已知 CSS 区域时使用 rootSelector，已有 ref 时使用 rootRef，只查找特定文案或角色时使用 query；仅需要当前视口内的控件时使用 mode: "interactive"，避免整页 AX Tree 占用上下文。视口内缺少 AX 控件语义时，interactive 会自动回退到 viewport，并返回 fallbackMode: "viewport"。重复文本点击可用 scope 限定子树，滚动子节点所在容器可用 containerPolicy: "nearest"。

页面动作传 observe: false 可关闭内置观察仅执行裸动作；不需要在每次动作后固定追加 wait、snapshot 或 screenshot。

browser_page_click.clickMode 默认 auto：可见桌面页使用可信 mouse，移动模拟页使用可信 touch；目标页隐藏时不会切换标签或还原窗口，而是使用 DOM fallback，并返回 dispatchMode: "dom"、fallbackReason: "page-hidden"。可用 dom / mouse / touch 覆盖自动策略；可信输入返回实际 pointerType。

安装

方式一：使用 npx（推荐，保持最新）

# 直接运行配置向导，会自动生成 npx 配置
npx @mearl/mcp-server --configure

方式二：全局安装（启动更快）

# 全局安装
npm install -g @mearl/mcp-server

# 运行配置向导
mearl-mcp-configure

配置向导会自动完成所有设置，支持 VSCode Copilot、Claude Code、Cursor。完成后重启 MCP 客户端即可使用。

使用

打开任意淘宝/飞猪页面，在 AI 客户端中发送：

获取最近 5 个请求
帮我分析购物车相关的接口
把购物车总价改成 150 元测试一下

本地开发

cd mcp-server
npm install
npm run build
npm link

运行配置向导，选择使用自定义 Extension ID：

mearl-mcp-configure
# 选择 "使用自定义 Chrome 插件 ID？" -> Yes
# 输入你的开发版 Extension ID

💡 在 chrome://extensions/ 查看你的 Extension ID

发布新版本：

npm version patch
npm run build
npm publish --access public

卸载

# 全局安装的版本
mearl-mcp-uninstall

# 或使用 npx
npx @mearl/mcp-server --uninstall

故障排查

配置失败：检查目录权限和路径是否存在

# macOS
mkdir -p ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts

"Native host has exited"：删除配置后重新运行

rm ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.alibaba.mearl.mcp.*

Extension ID 不匹配：使用 mearl-mcp-configure 重新配置

查看日志：

• MCP Server: AI 客户端的输出面板
• Chrome Extension: chrome://extensions/ → Mearl → background page

License

ISC