nodriver-mcp

ローカルの Codex MCP サーバーで、nodriver を使用した認証済みブラウザリサーチを実現します。専用の Chromium/Helium プロファイルを実行間で保持し、タスク固有の Python スクレイパーをホットリロードします。

セットアップ

Python 3.11+、uv、および Chromium ベースのブラウザが必要です。

uv sync --locked

以下を ~/.codex/config.toml に追加し、すべてのプレースホルダーを絶対パスに置き換えてください。

[mcp_servers.nodriver]
command = "uv"
args = ["--directory", "<path-to-nodriver-mcp>", "run", "--frozen", "nodriver-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 600

[mcp_servers.nodriver.env]
NODRIVER_MCP_BROWSER_EXECUTABLE = "<path-to-helium-or-chromium>"
NODRIVER_MCP_USER_DATA_DIR = "<path-to-a-dedicated-browser-profile>"
NODRIVER_MCP_SCRIPTS_DIR = "<path-to-nodriver-mcp>/scrapers"
NODRIVER_MCP_ARTIFACTS_DIR = "<path-to-nodriver-mcp>/artifacts"

MCP 設定を変更した後は Codex を再起動してください。ブラウザは遅延起動します。デフォルトでは可視モードで起動するため、専用プロファイルに一度サインインできます。そのクッキーは永続化されます。Codex は、プロンプトが明示的にヘッドレスブラウジングを要求した場合に headless=true を渡し、それ以外の場合は可視モードを選択します。モードを切り替えると管理対象ブラウザが再起動されますが、プロファイルは保持されます。

Related MCP server: scout-mcp-server

使用方法

Codex に、例えば次のように依頼します。

ブラウザセッションを使って example.com で一致するアイテムを見つけてください。ページを検査し、再利用可能なスクレイパーを作成し、実行し、大きな結果はアーティファクトとして保存してください。ヘッドレスモードで実行してください。

Codex はブラウザツールでページを検査し、スクレイパーを保存して実行できます。scraper_run を実行するたびにファイルが再読み込みされるため、MCP サーバーを再起動せずに編集を反映できます。

async def scrape(ctx, params):
    if url := params.get("url"):
        await ctx.goto(url)

    items = await ctx.evaluate_json("""
        Array.from(document.querySelectorAll('article')).map(item => ({
            title: (item.querySelector('h2')?.innerText || '').trim(),
            href: item.querySelector('a')?.href || null
        }))
    """)
    return {"items": items}

エントリポイントは async def scrape(ctx, params) で、JSON 互換のデータを返す必要があります。1 回の一括 ctx.evaluate_json(...) 呼び出しを推奨します。大きな結果には ctx.write_artifact(...) を使用してください。スクレイパーは非同期操作を使用し、すべてのタスクを完了してから返す必要があります。

テスト

uv run --frozen ruff check src tests
uv run --frozen pytest

セキュリティ

このサーバーは STDIO 経由でのみローカルで実行してください。スクレイパーはサンドボックス化されていない Python で、MCP プロセスの OS アクセス権と認証済みブラウザの制御権を持ちます。クッキー、トークン、パスワード、DevTools エンドポイントを絶対に公開しないでください。ページコンテンツは信頼できないものとして扱い、アクセスが許可されたデータのみを使用し、サイトの利用規約とレート制限を尊重してください。ブラウザプロファイル、生成されたスクレイパー、アーティファクトには個人データが含まれる可能性があるため、コミットしないでください。