gecko-mcp

gecko-mcp

一个 MCP（Model Context Protocol） 服务，让 AI 助手——Claude Code、 Claude Desktop、Cursor 以及任何 MCP 客户端——都能在 Floorp 和其他基于 Firefox 的浏览器 （LibreWolf、Waterfox、Zen、Mullvad、Firefox……）中读取页面、截取屏幕截图并管理标签页，使用的是真实登录会话。

可以把它想成面向整个 Firefox/Gecko 家族的“Chrome 中的 Claude”。

约 30 秒即可开始：

npx gecko-mcp setup

此命令会将 gecko-mcp 注册到 Claude Code、Claude Desktop、Cursor、VS Code（Copilot）、Windsurf、Zed、Codex 等客户端，可按项目或全局注册。手动配置请参阅设置，浏览器的一次性配置步骤请参阅要求。

担心安装这个工具？ 很好，你确实应该谨慎。它很小（只有 2 个依赖，全部位于 src/），默认锁定 OS 键盘和鼠标（除非你主动选择启用，否则只能操作浏览器），发布版本附带 npm 来源证明（可与此源代码核验），完整威胁模型见 SECURITY.md。运行 npx gecko-mcp 前请先阅读。

工作原理

gecko-mcp 通过以下两种后端之一与浏览器通信，并自动选择：

• Floorp 内置自动化 HTTP API。将 about:config 中的 floorp.mcp.enabled = true 设置为 true 后，gecko-mcp 会使用速度更快的 http://127.0.0.1:58261 API — 无需扩展，功能最丰富。
• 任何其他 Gecko 浏览器 — 使用 Marionette（每个 Firefox 分支都内置的自动化 引擎）启动浏览器，gecko-mcp 通过它操控你的实时会话。 工具相同，会话也是真实的。

  Claude Code / Desktop / Cursor
            │  MCP (stdio)
            ▼
      gecko-mcp ──► Floorp :58261 (built-in API)        ─┐
   (this project) ──► Marionette :2828 (any Gecko fork)  ─┴─► your real tabs

要求

• 已安装并运行的基于 Firefox 的浏览器，且已启用自动化：
  • Floorp： 在 about:config 中将 floorp.mcp.enabled 设置为 true，然后重启 Floorp。
  • 其他分支（LibreWolf / Waterfox / Zen / Mullvad / Firefox）： 使用 -marionette 启动 浏览器（参见浏览器支持）。
• Node.js ≥ 18。

设置

快速开始 — 设置向导

npx gecko-mcp setup

交互式向导会将 gecko-mcp 注册到你选择的 AI 编码工具——Claude Code、Cursor、Windsurf、VS Code（Copilot）、Gemini CLI、Codex、 Zed、Cline（还提供可复制粘贴的配置片段，适用于 Kimi Code、Antigravity 或任何其他 MCP 客户端）——并允许你选择仅用于当前项目或**全局（所有仓库）**安装。它会合并现有配置（并先创建备份）。

非交互式／可编写脚本的方式：

npx gecko-mcp setup --list                          # show supported tools
npx gecko-mcp setup --tool claude-code,cursor --scope global
npx gecko-mcp setup --tool codex --scope global --print   # dry run

手动配置

任何 MCP 客户端都可以使用此服务配置块（无需克隆或构建 — npx 会获取所需内容）：

{
  "mcpServers": {
    "gecko": {
      "command": "npx",
      "args": ["-y", "gecko-mcp"]
    }
  }
}

也可以使用 Claude Code 的 CLI：claude mcp add gecko -s user -- npx -y gecko-mcp。

Floorp 一次性设置： 在 about:config 中将 floorp.mcp.enabled = true 设置为 true，然后 重启 Floorp，以启用其自动化 API。

浏览器支持

gecko-mcp 会自动选择后端：如果可以访问 Floorp 的 :58261 API，就使用该 API；否则会连接到所有 Gecko 浏览器内置的自动化引擎 Marionette。若要使用非 Floorp 浏览器，请先启用 Marionette 并启动浏览器：

浏览器	启动时启用 Marionette
Floorp	（无需参数 — 只需设置 floorp.mcp.enabled=true；使用原生 API）
Firefox	firefox -marionette
LibreWolf	librewolf -marionette
Waterfox	waterfox -marionette
Zen	zen -marionette
Mullvad	mullvad-browser -marionette

Marionette 默认监听 TCP 2828 端口。若要使用其他端口，请在配置文件中设置 marionette.port 首选项（例如通过 user.js），并使用匹配的 MARIONETTE_PORT 启动 gecko-mcp。使用 GECKO_MCP_BACKEND=marionette 强制指定后端。

注意： 必须在启动时启用 Marionette，才能连接到当前运行的会话。 在 Marionette 后端上，仅适用于 Floorp 的扩展功能（snapshot 指纹、 list_workspaces/switch_workspace、无障碍树）会返回清晰的 “不支持”提示 — 请改用 find / read_page。其他功能 （标签页、导航、点击、输入、表单、截图、Cookie、真实 OS 输入等）均可使用。

工具

标签页与阅读

工具	功能说明
list_tabs	列出所有打开的标签页（标题、URL、browserId、是否活动、是否固定）。
open_tab	在 URL 处打开新标签页；返回新标签页的 browserId，以便指定目标。
get_active_tab	返回活动标签页的标题、URL 和 browserId。
navigate_tab	将现有标签页导航到某个 URL。
close_tab	关闭标签页。
read_page	将标签页内容读取为整洁的 Markdown（或 HTML / 无障碍树）。输出设有上限（默认 25 KB），以保护上下文。
find	快速元素定位器 — 在服务端按可见文本和/或标签搜索页面；返回精简的可直接使用的 CSS selector 列表（约 1 KB），而非整个 HTML。可用它查找按钮/链接/字段，然后对该 selector 执行操作。
snapshot	结构化页面映射：包含内嵌 fp: 引用的 Markdown 和元素 selector 映射 — 无需搜索 HTML 即可定位元素，然后通过 ref 执行操作。
screenshot	截取标签页的屏幕截图（视口或整页）。
launch_floorp	确保 Floorp 正在运行 — 如果无法访问 API，则启动 Floorp（Windows）。
launch	启动任意基于 Firefox 的浏览器（Firefox、LibreWolf、Zen 等）并启用 Marionette，以便 gecko-mcp 控制浏览器。

交互

工具	功能说明
click	按 CSS selector 或 snapshot 中的 ref 点击元素；会先自动滚动，使元素进入视野。
type_text	按 CSS selector 在输入框/文本区域中输入 — 也支持富文本/可编辑内容的编辑器（Slate、ProseMirror 等）。
fill_form	一次填写多个字段。
press_key	按下键盘按键（Enter、Tab 等）。
wait_for_element	等待元素挂载/变为可见等。
get_value	敏感。 读取输入框/文本区域/选择框的当前值（可能读取密码字段）。

大多数工具默认针对活动标签页；传入 browserId（来自 list_tabs）即可指定目标标签页。

OS 键盘和鼠标 — 默认锁定 🔒

以下工具可能影响浏览器以外的内容，因此在启用之前会保持禁用状态。如果没有设置任何选项，gecko-mcp 只会执行浏览器自动化。只需提出请求（“enable OS input”，这会调用 enable_os_input 工具）即可为当前会话解锁；也可以通过 GECKO_MCP_ENABLE_OS_INPUT=1 持久启用。使用 disable_os_input 重新锁定。锁定期间，这些工具会拒绝执行，并给出明确提示。

evaluate 工具（运行任意页面 JavaScript）也以相同方式锁定——使用 enable_evaluate 解锁，或设置 GECKO_MCP_ENABLE_EVALUATE=1。

工具	功能
enable_os_input / disable_os_input	为当前会话解锁／重新锁定 OS 键盘和鼠标工具。
enable_evaluate / disable_evaluate	为当前会话解锁／重新锁定 evaluate（运行页面 JS）工具。
evaluate	已锁定。 在页面中运行 JavaScript 并返回其值（return …）。

真实 OS 键盘（Windows） — 适用于 React／富文本编辑器，以及会忽略模拟输入的机器人防护提交操作：

工具	功能
real_type	通过真实 OS 按键事件（isTrusted）在聚焦的元素中输入内容。
real_key	按下真实按键或组合键，例如 "Enter"、"ctrl+a"。
real_clear	执行真实的 Ctrl+A + Delete 操作，可可靠清空富文本／contenteditable 字段。

这些工具产生的输入无法被页面与真人输入区分，因此可操作 React／Slate 编辑器，以及无法通过模拟点击／输入操作的提交编辑框。工作流：点击字段使其获得焦点 → real_clear / real_type / real_key "Enter"。

安全防护： OS 按键会发送到前台窗口，因此在发送任何内容之前，这些工具会将 Floorp 置于前台并进行验证——如果 Floorp 未运行或无法聚焦，工具会立即中止，不会输入任何按键，因此输入绝不会泄漏到其他应用中。

真实 OS 鼠标（Windows） — 在屏幕坐标处执行真实的 isTrusted 点击：

工具	功能
window_bounds	Floorp 窗口在屏幕像素中的矩形区域（用于计算目标位置）。
move_cursor	将真实 OS 光标移动到 Floorp 内的屏幕像素位置。
real_click	在 Floorp 内的屏幕像素位置执行真实 OS 点击（左键／右键，单击／双击）。

双重防护： 只有在确认 Floorp 位于前台且点击位置位于 Floorp 窗口矩形区域内时，才会发送点击——遇到意外坐标时会拒绝执行，因此点击绝不会落在其他应用／窗口中。坐标单位为屏幕像素（根据屏幕截图映射坐标时，请注意显示缩放／DPI）。

更多交互与查询

工具	功能
hover / double_click / right_click	对元素执行鼠标操作（使用选择器或 ref）。
select_option	在 <select> 中选择一个选项。
set_checked	勾选／取消勾选复选框或单选按钮。
submit_form	提交表单。
upload_file	敏感操作。 通过绝对路径设置文件 <input> — 使用 GECKO_MCP_ALLOW_UPLOAD_DIRS 限制可用目录。
get_attribute	读取元素属性（href、value、……）。
get_article	将通过 Readability 提取的正文文章读取为 Markdown。
get_cookies	敏感操作。 读取页面可见的 Cookie — 除非设置 includeValues: true，否则会隐藏其值。
wait_for_network_idle	等待网络活动停止。
list_workspaces / switch_workspace	Floorp 工作区（视支持情况而定）。

安全性

启用此功能之前，请了解其威胁模型。主要有两种风险：

1. Floorp 的自动化 API 默认没有身份验证。 启用 floorp.mcp.enabled 后，任何本地进程都可以通过 127.0.0.1:58261 操控已登录的浏览器，而不仅限于此服务。此外，API 不会检查 Origin，因此 恶意网页可能会尝试利用 CSRF/DNS 重绑定伎俩攻击它。缓解措施：
   • 不使用自动化功能时，将 floorp.mcp.enabled 关闭。
   • 设置 GECKO_MCP_TOKEN 环境变量——此服务随后会在每个请求中将其作为 Bearer 令牌发送（仅在强制要求令牌的 Floorp 构建版本中生效；其他情况 不会造成影响）。
2. 提示词注入（“致命三要素”）。 助手会读取不可信的网页内容，并且 能操作已通过身份验证的会话（点击、输入、提交、导航，以及真实的操作系统 输入）。恶意网页可能会试图指使助手做出对你不利的操作。请将从网页读取的 所有内容视为不可信；不要在不信任的网站上无人值守地运行自动化。

此服务内置的安全加固措施：

• 默认锁定操作系统键盘/鼠标（最小权限）： 只有明确解锁后 （通过 enable_os_input 工具，或设置 GECKO_MCP_ENABLE_OS_INPUT=1）， 才能运行那些可在浏览器之外执行操作的工具。默认情况下，gecko-mcp 只能 自动化操作浏览器，无法操作你设备上的其他内容。
• 真实的操作系统输入受双重保护： 只有确认 Floorp 是前台窗口后才会发送 按键/点击，并且鼠标点击必须落在 Floorp 窗口范围内，否则会中止操作，不会 发送任何内容。PowerShell 负载通过进程专用的环境变量以 base64 编码形式传递 （不进行 shell 插值，也不会在磁盘上创建临时脚本文件）。
• URL scheme 与主机允许列表： open_tab/navigate_tab 默认只接受 http(s)（以及 about:blank），并且拒绝环回/私有主机 （127.0.0.1、localhost、10/8、172.16/12、192.168/16、169.254/16、 IPv6 ULA/链路本地地址）。这可以阻止受提示词注入影响的 Agent 将浏览器转向 Floorp 自身的 API 或你的局域网，并读取响应。设置 GECKO_MCP_ALLOW_PRIVILEGED_URLS=1 可取消此限制。也可以通过 GECKO_MCP_ALLOW_DOMAINS 将导航限制在指定的域名允许列表中。
• get_cookies 默认会隐去 Cookie 值；必须显式设置 includeValues: true 才能获取原始值。
• get_value 可能会读取机密信息： 浏览器允许同源 JS 读取密码字段，因此 此工具可能会返回已输入的密码。此工具标记为 SENSITIVE——仅用于读取用户 指定的字段，绝不可用于窃取凭据。
• 上传允许列表： 设置 GECKO_MCP_ALLOW_UPLOAD_DIRS（以 ; 分隔的目录） 可限制 upload_file 的访问范围。路径会通过 realpath 规范化（解析符号链接）， 并进行检查，确保 ..、符号链接、前缀相同的同级目录或 UNC 路径无法逃出 允许的文件夹。
• find 会跳过隐藏元素（内联 display:none/visibility:hidden、 hidden、type=hidden、aria-hidden），以防网页通过文本搜索诱使 Agent 点击不可见按钮。
• 输入范围限制： 数值/文本工具参数均设有范围和长度上限（坐标、超时时间、 maxChars、find 的结果数量限制、输入文本、表单字段），以防资源耗尽或 输入内容导致崩溃。
• 截断 API 错误并验证端口： Floorp 错误响应正文会在传给模型前截断； GECKO_MCP_PORT 会验证为 1–65535。
• 面向人工介入的工具注解： 每个工具都带有 MCP 提示 （readOnlyHint/destructiveHint/…），以便客户端自动运行只读工具，并在 执行有破坏性的操作时请求确认（close_tab、navigate_tab、submit_form、 upload_file）。服务本身无法显示提示——审批由客户端负责——因此 gecko-mcp 会通过这种方式告知客户端哪些操作安全，哪些可能造成重大影响。
• 不提供 evaluate 工具： 出于有意的安全考虑，不开放任意执行网页 JS 的 功能。 无法防御的情况（固有局限／Floorp 端）：恶意的本地进程仍可读取或冒充未经身份验证的环回 API（明文传输，无 TLS）；而你选择自动化的页面也仍可能通过提示词注入驱动合法操作。闲置时请禁用 floorp.mcp.enabled，不要在无人值守的情况下自动化不可信网站。

环境变量	作用
GECKO_MCP_TOKEN	以 Authorization: Bearer … 的形式发送到 Floorp API。
GECKO_MCP_PORT	API 端口（默认 58261，有效范围为 1–65535）。
GECKO_MCP_ALLOW_PRIVILEGED_URLS	设为 1 时，允许在 open/navigate 中使用非 http(s) URL 以及环回／私有主机。
GECKO_MCP_ALLOW_DOMAINS	以逗号分隔的导航域名允许列表（包含子域名）。未设置 = 允许任何公共主机。
GECKO_MCP_ALLOW_UPLOAD_DIRS	将 upload_file 限制在这些目录中（以 ; 分隔）。
FLOORP_PATH	launch_floorp 使用的 floorp.exe 完整路径。
GECKO_MCP_BACKEND	强制指定后端：floorp 或 marionette。默认：自动检测。
MARIONETTE_PORT	非 Floorp 浏览器的 Marionette TCP 端口（默认 2828）。
GECKO_MCP_ENABLE_OS_INPUT	设为 1 时，启动时启用 OS 键盘／鼠标工具（否则会保持锁定，直到调用 enable_os_input 工具）。
GECKO_MCP_ENABLE_EVALUATE	设为 1 时，启动时启用 evaluate（运行页面 JS）工具（否则会保持锁定，直到调用 enable_evaluate）。
GECKO_MCP_BROWSER_PROCESS	真实 OS 键盘／鼠标可操作的进程名称正则表达式（默认涵盖常见的 Gecko 分支）。

旧版 FLOORP_MCP_* 变量名称仍可作为备用项使用（这是重命名前的名称），因此现有配置仍可正常工作 — 后续请优先使用 GECKO_MCP_*。

性能

• HTTP 工具调用开销很低 — 针对 Floorp 本地 API 的完整连接 → 操作 → 断开往返耗时约为 5–6 ms。find 会在服务端搜索页面，并返回约 1 KB 的可直接使用的选择器，而不是转储整个 HTML；read_page 也有大小上限（默认 25 KB），因此读取页面不会占满上下文。
• 真实 OS 输入使用持久 PowerShell 主机。 过去每次调用 real_*/move_cursor/window_bounds 时都要启动 powershell.exe（约 700 ms）并编译 P/Invoke 辅助程序（约 600 ms），每次耗时约 1.9 s。现在会按需启动一个主机，只编译一次，然后运行读取-求值循环 — 因此首次调用耗时约 1.6 s，之后每次执行受保护的按键／点击约 350 ms（速度提升约 5 倍），查询窗口边界只需几毫秒。每条命令仍会执行前台窗口／边界安全检查；如果主机挂起或退出，则会重新创建。

备注与限制

从操作真实应用（包括 Google Flow）的实践中总结：

• 富文本编辑器： type_text 支持普通输入框和 contenteditable 编辑器（Slate、ProseMirror、Lexical）— 如果元素没有 .value，则会改为分发真实的文本输入事件。目前尚未解决如何可靠地清空这类编辑器（没有 select-all/evaluate）。
• 提交 React 输入框： 许多聊天／提示词输入框需要真实的 Enter keydown 才会提交，而不是合成点击发送按钮。对于这类输入框，优先使用 press_key "Enter"，而不是 click。
• 可信事件： 无法通过页面 JavaScript 伪造 isTrusted=true — 这是浏览器安全不变量。Floorp 会在特权层注入输入，因此普通点击／按键的行为与真实操作相同；但受 reCAPTCHA 或严格机器人检测保护的流程仍可能拒绝自动提交。
• evaluate： 某些 Floorp 版本的页面 JS 求值端点会返回 HTTP 404，因此此处不会将其作为工具提供。
• 多个窗口： 打开多个窗口时，“活动标签页”存在歧义（每个窗口都有自己的活动标签页）。优先使用 open_tab 返回的 browserId，或使用 list_tabs 返回的 ID，并将其显式传递给每个工具。

路线图

• 标签页管理、页面阅读、截图
• 交互工具：点击、输入、填写表单、按键、读取字段值
• 真实 OS 键盘（Windows）：real_type / real_key / real_clear，带前台安全防护 — 可操作 React/Slate 编辑器并提交受机器人防护的表单
• snapshot（指纹引用 + 选择器映射）+ 按 ref 点击 + 自动滚动至可见区域
• launch_floorp — 如果 Floorp 尚未运行，则启动它（Windows）
• 其他工具：悬停、双击/右键、select_option、set_checked、提交、upload_file、get_attribute、get_article、get_cookies、wait_for_network_idle、工作区
• 真实 OS 鼠标（Windows）：window_bounds / move_cursor / real_click，带前台状态 + 窗口内边界双重防护
• Marionette 后端 — 适用于所有基于 Firefox 的浏览器（LibreWolf、Waterfox、Zen、Mullvad、Firefox……），当 Floorp API 不可用时自动选择
• macOS / Linux 原生输入后端
• JS evaluate（较新的 Floorp 版本可用；较旧版本会返回 HTTP 404）
• 可选的 bearer-token 身份验证
• 为非 Floorp 浏览器提供 launch 辅助工具（使用 -marionette 启动浏览器）

致谢

基于 Floorp 提供的自动化 API 构建。官方的 Floorp-Projects/floorp-mcp-server 为梳理端点范围提供了有用的参考。本项目是一个独立的、从零实现的 MIT 许可项目。

许可证

MIT © Frumane