yetibrowser-mcp

🚀 YetiBrowser MCP

YetiBrowser MCP是浏览器MCP工作流程的完全开源实现。它将基于Node的MCP服务器与Chrome/Firefox扩展相连接，使得模型上下文协议（Model Context Protocol）客户端（如Codex/Claude Code、Cursor、Windsurf、MCP Inspector或你自己的工具）能够自动化操作真实的浏览器标签页，同时确保每一个字节的数据都保留在你的设备上，并且可审计。

🚀 快速开始

MCP浏览器扩展安装

Chrome浏览器

• 在此处安装最新的Chrome浏览器扩展：https://chromewebstore.google.com/detail/hpedknkjljpopinabjjmljgckhlancni?utm_source=item-share-cb
• 除非你运行了多个YetiBrowser MCP服务器实例，否则请将其保持在自动连接模式。

Firefox浏览器（当前不可用）

由于Firefox稳定版中Manifest v3的功能有限，Firefox扩展将暂停开发，直到全面支持（非Nightly版本）普遍可用。

MCP服务器安装

Codex CLI

• 编辑你的~/.codex/config.toml文件，并添加MCP条目：

[mcp_servers.yetibrowser-mcp]
command = "npx"
args = ["-y", "@yetidevworks/server"]

• 重启codex CLI命令；你应该会在/mcp工具列表中看到yetibrowser-mcp。
• 如果你想指定一个特定的端口，可以使用以下格式的args条目：args = ["-y", "@yetidevworks/server", "--ws-port", "9010"]

Claude Code

• 确保扩展已安装并连接到一个标签页，然后使用npx -y @yetidevworks/server启动MCP服务器（或者运行本地构建的CLI）。
• 将服务器条目添加到~/Library/Application Support/Claude/claude_desktop_config.json文件中（请参阅docs/publishing.md中的示例）。
• 重启claude，以便它能识别新的MCP服务器；扩展连接后，你应该会在/mcp工具菜单中看到yetibrowser-mcp。

其他支持MCP的客户端

• 任何MCP客户端都可以通过启动CLI（npx -y @yetidevworks/server）来连接，或者可选地指定一个特定的端口，例如npx -y @yetidevworks/server --ws-port 9010。
• 服务器通过标准输入输出暴露标准的MCP传输协议，因此当标签页连接时，使用你的客户端支持的任何配置机制来运行上述命令。

MCP Inspector

• 用于在编码代理之外进行测试和调试。
• 使用npx @modelcontextprotocol/inspector npx -y @yetidevworks/server -- --ws-port 9010来运行并结合YetiBrowser MCP浏览器扩展检查MCP服务器。

故障排除

• CLI会在9010 - 9020端口范围内寻找可用端口，找到时会记录switched to。如果你想固定一个特定的端口，可以传递--ws-port <port>参数。
• 浏览器扩展的弹出窗口会反映这种行为：将其保持在“自动”模式以跟踪CLI的端口，或者选择“手动”并输入browser_connection_info或CLI日志中报告的端口来覆盖它。
• 你可以直接询问你的AI工具连接端口。例如：what is the yetibrowser mcp connction info?，然后将报告的端口设置为手动端口。

✨ 主要特性

• 透明且可定制 – 无需下载二进制文件。你可以检查、分叉和扩展每个组件。
• 本地优先 – 扩展仅与本地主机的MCP服务器通信；浏览数据永远不会离开你的设备。
• 跨浏览器支持 – 共享逻辑支持Chrome和Firefox扩展包（由于Firefox对Manifest V3的支持尚不完善，Firefox版本的构建暂未完成，因此在Mozilla推出完整的MV3 API之前，连接的用户体验可能会受到限制）。
• 面向开发者的工具 – 提供更丰富的控制台捕获、DOM差异比较、页面状态转储和全页截图功能，用于调试和质量保证。
• 适合生产环境 – 提供用于打包、发布和集成到IDE工作流程的脚本和文档。

📦 安装指南

MCP浏览器扩展安装

Chrome浏览器

• 在此处安装最新的Chrome浏览器扩展：https://chromewebstore.google.com/detail/hpedknkjljpopinabjjmljgckhlancni?utm_source=item-share-cb
• 除非你运行了多个YetiBrowser MCP服务器实例，否则请将其保持在自动连接模式。

Firefox浏览器（当前不可用）

由于Firefox稳定版中Manifest v3的功能有限，Firefox扩展将暂停开发，直到全面支持（非Nightly版本）普遍可用。

MCP服务器安装

Codex CLI

• 编辑你的~/.codex/config.toml文件，并添加MCP条目：

[mcp_servers.yetibrowser-mcp]
command = "npx"
args = ["-y", "@yetidevworks/server"]

• 重启codex CLI命令；你应该会在/mcp工具列表中看到yetibrowser-mcp。
• 如果你想指定一个特定的端口，可以使用以下格式的args条目：args = ["-y", "@yetidevworks/server", "--ws-port", "9010"]

Claude Code

• 确保扩展已安装并连接到一个标签页，然后使用npx -y @yetidevworks/server启动MCP服务器（或者运行本地构建的CLI）。
• 将服务器条目添加到~/Library/Application Support/Claude/claude_desktop_config.json文件中（请参阅docs/publishing.md中的示例）。
• 重启claude，以便它能识别新的MCP服务器；扩展连接后，你应该会在/mcp工具菜单中看到yetibrowser-mcp。

其他支持MCP的客户端

• 任何MCP客户端都可以通过启动CLI（npx -y @yetidevworks/server）来连接，或者可选地指定一个特定的端口，例如npx -y @yetidevworks/server --ws-port 9010。
• 服务器通过标准输入输出暴露标准的MCP传输协议，因此当标签页连接时，使用你的客户端支持的任何配置机制来运行上述命令。

MCP Inspector

• 用于在编码代理之外进行测试和调试。
• 使用npx @modelcontextprotocol/inspector npx -y @yetidevworks/server -- --ws-port 9010来运行并结合YetiBrowser MCP浏览器扩展检查MCP服务器。

💻 使用示例

基础用法

你可以使用以下命令启动MCP服务器：

npx -y @yetidevworks/server

📚 详细文档

仓库布局

• packages/shared – 消息和工具模式的共享TypeScript定义。
• packages/server – 将MCP客户端连接到运行中的浏览器标签页的MCP服务器。
• extensions/shared – 共享的扩展源文件（后台/弹出窗口）和资源。
• extensions/chrome / extensions/firefox – 每个浏览器的打包层。
• docs/ – 工作区命令、发布清单和功能说明。
• scripts/ – 辅助实用工具，例如用于生成发布压缩包的package-extensions.sh脚本。

MCP可用工具

• browser_snapshot – 捕获当前页面的可访问性快照
• browser_snapshot_diff – 比较最近的两个快照，突出显示DOM/ARIA的变化
• browser_navigate – 在连接的标签页中加载新的URL并返回更新后的快照
• browser_go_back / browser_go_forward – 在浏览历史中前进或后退，同时保持MCP同步
• browser_wait – 暂停自动化操作指定的秒数
• browser_wait_for – 等待直到指定的选择器元素出现（可选地要求元素可见）后再继续执行
• browser_press_key – 在聚焦元素上模拟键盘按键按下操作
• browser_click – 点击由CSS选择器指定的元素
• browser_hover – 将鼠标指针悬停在目标元素上
• browser_drag – 将元素拖动到拖放目标上，适用于可排序或拖放式用户界面
• browser_type – 在可编辑元素中输入文本（可选地使用Enter键提交）
• browser_fill_form – 一次性填充多个输入框、选择框、复选框或单选框
• browser_select_option – 在<select>元素中选择一个或多个选项
• browser_screenshot – 通过DevTools协议捕获视口或全页截图
• browser_get_console_logs – 返回最近的控制台输出，包括带有堆栈跟踪的错误信息
• browser_page_state – 转储连接页面的表单、存储键和cookie信息
• browser_connection_info – 报告桥接WebSocket端口、连接状态和扩展版本
• browser_evaluate – 在页面内运行自定义JavaScript代码并返回JSON可序列化的结果
• browser_handle_dialog – 接受或关闭alert/confirm/prompt对话框，可选择提供提示文本

文档与构建脚本

• 工作区命令文档位于docs/workspace-commands.md。
• 发布步骤（npm + 扩展商店）文档位于docs/publishing.md。
• 截图功能的文档位于docs/screenshot.md。
• 使用./scripts/package-extensions.sh脚本生成可分发的Chrome/Firefox压缩包（输出到artifacts/目录）。
• 仓库级别的隐私政策文档位于PRIVACY.md。