ff-mcp

ff-mcp は、ローカル MCP クライアントに、既に使用している Firefox プロファイルへの制御付きアクセスを提供します。これは、Firefox Manifest V3 WebExtension と、127.0.0.1 上の Streamable HTTP で MCP を提供する Python Native Messaging ホストで構成されています。

拡張機能（localhost プロセスではなく）が最終的な認可境界です。タブのメタデータを一覧表示しても、ページコンテンツへのアクセスは許可されません。読み取り、操作、スクリーンショットには、独立した取り消し可能な権限が必要です。

現在の機能

• ページアクセスなしでタブのメタデータを一覧表示します。

• 特定のタブで READ、INTERACT、SCRIPT、SCREENSHOT を要求します。

• 一度だけ、ドキュメント単位、タブセッション単位、またはホストに対して永続的にアクセスを許可します。

• 制限付きのシリアライズされたスナップショットと CSS クエリ結果を読み取ります。ライブ DOM オブジェクトがブリッジを越えることはありません。

• 構造化された操作によるクリック、入力、スクロール、ナビゲーション。

• タブのキャプチャは、別途スクリーンショットの許可がある場合のみ可能です。

• 分離されたユーザースクリプトワールドまたはページのメインコンテキストで任意の JavaScript を実行するには、別途 SCRIPT の許可と Firefox のオプションの userScripts 権限が必要です。

• AND、OR、NOT で構成される host、glob、regex、scheme 述語を使用して永続ポリシーを照合します。

• Firefox 内の認可判断と機密操作を監査します。

• MCP をループバックのみにバインドし、生成されたベアラートークンを要求し、デフォルトで HTTP オリジンを拒否します。

要件

• Firefox 150 以降。

• Python 3.14（パッケージは 3.14 マイナーバージョンに固定されています）。

• インストールには uv を推奨します。

1回限りの 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. 1つ以上の権限を指定して browser_request_access を呼び出します。

3. Firefox でツールバーのリクエストを承認します。

4. 読み取り、操作、またはスクリーンショットツールを呼び出します。

5. ツールバーまたは browser_revoke で許可を取り消します。

READ はデフォルトで localhost、.localhost のサブドメイン、127.0.0.0/8、::1 に対してのみ許可されます。このデフォルトには、操作、スクリプト実行、スクリーンショットは含まれません。

ポリシールール

オプションページにはビジュアルなポリシーエディタがあります。新しいルールは、OR 許可グループと NAND 除外グループを含むメインの AND コンテナで始まります。ホスト、URL パターン、正規表現、スキームの条件を追加し、必要に応じて AND、OR、NAND、NOR コンテナをネストしてから、一致するルールが許可する権限を選択します。

空の否定されていないコンテナは何にも一致しません。空の否定されたコンテナはすべてに一致するため、許可グループに少なくとも1つの条件ができるまで、新しいルールは無効のままです。常に有効な localhost READ ルールは別途表示され、編集または削除できません。

既存の式ベースのルールは、設定ページを開くとビジュアルツリーに移行されます。式形式は後方互換性のために保存表現として残ります。

正規表現パターンは長さ制限があり、後方参照、先読み・後読み、明らかなネストされた量指定子を拒否します。これは安全なサブセットであり、完全な 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 資格情報の発行者。

• AMO_JWT_SECRET: 対応する AMO API シークレット。

資格情報は AMO API キーページ から作成します。非公開署名では、AMO の検索や一覧に拡張機能が公開されることはありません。

セキュリティ上の制限

• 拡張機能は、任意のタブを仲介し、Firefox のバックグラウンドタブのスクリーンショット API を使用できるようにするため、必然的に広範なサイトアクセスを要求します。したがって、内部の権限チェックが重要です。

• 承認されたブラウザのメタデータ、Web サイトのコンテンツ、Web サイトのアクティビティは、ローカルのネイティブホストと MCP クライアントに送信されます。AMO はインストール時にこれらの必要なデータカテゴリを宣言します。

• about: やアドオンストアなどの Firefox で制限されているページは、コンテンツスクリプトで読み取ることができません。

• タブセッションの許可は、そのタブでのナビゲーション後も意図的に維持されます。ドキュメントの許可は維持されません。

• MCP クライアントの ID は、単一のベアラートークンの信頼ドメイン内でのみ記述的です。相互に信頼できないローカルクライアントの分離が必要な場合は、別の設定とトークンを使用してください。

• 構造化されたクリックや入力によって、ページの動作がトリガーされる可能性があります。INTERACT は控えめに許可してください。

• SCRIPT は事実上ページ全体の制御を意味します。Firefox は承認中にオプションの userScripts 権限を要求し、ff-mcp は引き続き別のタブ権限を必要とします。MAIN ワールドのスクリプトは、ページが所有する JavaScript の状態にアクセスして変更できます。これは信頼できるクライアントとサイトにのみ許可してください。

この実装に先立つ設計調査については、firefox_mcp_extension_findings.html を参照してください。

ライセンス

MIT。 LICENSE と THIRD_PARTY.md を参照してください。