ff-mcp

ff-mcp 为本地 MCP 客户端提供对您已在使用的 Firefox 配置文件的受控访问。它由一个 Firefox Manifest V3 WebExtension 和一个 Python Native Messaging 主机组成，后者在 127.0.0.1 上通过 Streamable HTTP 提供 MCP 服务。

扩展——而非 localhost 进程——是最终的授权边界。列出标签页元数据并不授予访问页面内容的权限。读取、交互和截图需要独立且可撤销的能力。

当前能力

• 在不访问页面的情况下列出标签页元数据。

• 针对特定标签页请求 READ、INTERACT、SCRIPT 和 SCREENSHOT。

• 为文档、标签页会话或持久地为主机一次性授予访问权限。

• 读取有界的序列化快照和 CSS 查询结果。实时 DOM 对象永远不会跨过这座桥。

• 通过结构化操作进行点击、输入、滚动和导航。

• 只有在单独授予截图权限时才能捕获标签页。

• 只有在单独授予 SCRIPT 权限并拥有 Firefox 的可选 userScripts 权限时，才能在隔离的用户脚本世界或页面的主世界中执行任意 JavaScript。

• 使用 host、glob、regex 和 scheme 谓词，并通过 AND、OR 和 NOT 组合，来匹配持久策略。

• 在 Firefox 内部审计授权决策和敏感操作。

• 仅将 MCP 绑定到回环地址，要求使用生成的 bearer 令牌，并默认拒绝 HTTP 来源。

要求

• Firefox 150 或更高版本。

• Python 3.14（该包固定在 3.14 次要版本线上）。

• 建议使用 uv 进行安装。

一次性 SCRIPT 执行需要 Firefox 153 或更高版本，因为该版本引入了 userScripts.execute()。其余能力支持 Firefox 150 及以上版本。

从检出目录安装

将原生伴生程序安装为持久工具，然后将其注册到 Firefox：

uv tool install .
ff-mcp install-native

在开发时，从 about:debugging → 此 Firefox → 加载临时附加组件 加载 extension/manifest.json。

打开 ff-mcp 工具栏弹出窗口并按下 启动。首次启动会创建一个包含随机令牌的私有配置文件：

• Linux：$XDG_CONFIG_HOME/ff-mcp/config.json 或 ~/.config/ff-mcp/config.json

• macOS：~/.config/ff-mcp/config.json

• Windows：%APPDATA%\ff-mcp\config.json

该弹出窗口会显示并可以复制一个通用连接对象：

{
  "url": "http://127.0.0.1:8765/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_GENERATED_TOKEN"
  }
}

在支持 Streamable HTTP 和自定义请求头的 MCP 客户端中配置这些值。仅当扩展保持其 Native Messaging 连接打开时，该端点才存在。

权限流程

1. 调用 browser_tabs 并选择一个标签页 ID。

2. 使用一个或多个能力调用 browser_request_access。

3. 在 Firefox 中批准工具栏请求。

4. 调用读取、交互或截图工具。

5. 从工具栏或使用 browser_revoke 撤销授权。

默认情况下，READ 仅允许用于 localhost、.localhost 的子域、127.0.0.0/8 和 ::1。此默认值不包括交互、脚本注入或截图。

策略规则

选项页面有一个可视化策略编辑器。每个新规则都以一个主 AND 容器开始，其中包含一个 OR 允许组和一个 NAND 排除组。添加 host、URL 模式、正则或 scheme 条件；在需要时嵌套更多 AND、OR、NAND 或 NOR 容器；然后选择匹配规则所授予的能力。

空的非否定容器不匹配任何内容。空的否定容器匹配所有内容，因此新规则在其允许组至少有一个条件之前保持非活动状态。始终启用的 localhost READ 规则会单独显示，且无法编辑或删除。

当设置页面打开时，现有的基于表达式的规则会迁移到可视化树中。为了向后兼容，表达式格式仍然是存储表示形式。

正则模式有长度限制，并拒绝反向引用、环视（lookaround）以及明显的嵌套量词。这是一个安全子集，不是完整的 RE2 实现。

开发

UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv sync --group dev
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run pytest -q
# Opt-in: launches the installed Firefox headlessly with a fresh temporary profile.
FF_MCP_RUN_FIREFOX_TESTS=1 UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run pytest -q tests/test_firefox_integration.py
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run ruff check .
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run ruff format --check .
node tests/policy.test.js
node tests/rule-model.test.js
node tests/background.test.js
node tests/content.test.js
node --check extension/background.js
node --check extension/content.js
node --check extension/options.js
node --check scripts/check-web-ext-lint.js

对于 Selenium 无法自动发现的安装，请设置 FIREFOX_BINARY。集成测试无需额外配置即可识别标准 Linux Snap 位置。

Firefox 扩展没有运行时第三方依赖，也没有构建步骤。

发布

名为 vX.Y.Z 的标签会运行发布工作流。标签版本必须同时匹配 pyproject.toml 中的 project.version 和 extension/manifest.json 中的 version。该工作流请求 Mozilla Add-ons 在 unlisted 渠道上对扩展进行签名，验证返回的 XPI，并将签名后的 XPI 及其 SHA-256 校验和附加到 GitHub 发布版本中。生成的工件不会被跟踪。

在推送标签之前，请在仓库的 release 环境配置以下机密：

• AMO_JWT_ISSUER：来自 AMO API 凭据的签发者（issuer）。

• AMO_JWT_SECRET：对应的 AMO API 密钥。

从 AMO API 密钥页面 创建这些凭据。Unlisted 签名不会在 AMO 搜索或列表中发布扩展。

安全限制

• 该扩展必然请求广泛的站点访问权限，以便能够代理任意标签页并使用 Firefox 的后台标签页截图 API。因此，其内部能力检查至关重要。

• 经批准的浏览器元数据、网站内容和网站活动会传输到本地原生主机和 MCP 客户端。AMO 在安装期间会声明这些必需的数据类别。

• Firefox 限制的页面（如 about: 和附加组件商店）无法被内容脚本读取。

• 标签页会话授权有意在该标签页的导航后仍然有效；文档授权则不会。

• 在同一个 bearer 令牌信任域内，MCP 客户端身份只是描述性的。如果互不信任的本地客户端需要隔离，请使用单独的配置和令牌。

• 结构化点击和输入仍然可能触发页面行为。请谨慎授予 INTERACT。

• SCRIPT 实际上相当于对页面的完全控制。Firefox 在批准期间会请求其可选的 userScripts 权限，而 ff-mcp 仍然要求单独的标签页能力。MAIN 世界脚本可以访问和修改页面拥有的 JavaScript 状态；请仅将此权限授予你信任的客户端和站点。

请参阅 firefox_mcp_extension_findings.html，了解本实现之前的设计研究。

许可证

MIT。请参阅 LICENSE 和 THIRD_PARTY.md。