mcp-browser-lightpanda

Codex / Claude Code 向けの Lightpanda 専用 MCP サーバー

Docker 上の lightpanda/browser:nightly を使って、軽量ヘッドレスブラウザを AI エージェントから操作するための MCP サーバー。

---

概要

mcp-browser-local の姉妹版で、Chromium ではなく Lightpanda 専用に特化している。デスクトップのブラウザプロファイルを再利用したり GUI ブラウザにアタッチしたりはせず、Windows では Docker + 公式 lightpanda/browser:nightly イメージを前提に組んでいる。

設計方針

項目	方針
ブラウザ	Lightpanda のみ
トランスポート	stdio MCP
Windows 接続路	CDP over Docker を安定動作させる
タブ戦略	積極的な new_tab より単一 managed page を保持
ページ読み取り	軽量な document.title 直読み等
PDF 抽出	MCP 内で完結 (外部ツール不要)
セキュリティ	SSRF / path / cross-origin cookie / RCE 経路を全部 deny by default

姉妹版との違い

Lightpanda は Chromium じゃない。Chromium スタイルの target / context フローが不安定な場面があるので、この variant は:

• playwright-core の connectOverCDP(...) で実ランタイムに接続
• page.title() を避けて document.title を直接読む
• launch 時に primary managed page を作って保持
• browser_new_tab は「ブラウジング面の要求」として扱い、タブ追加を保証しない
• PDF は同一タブ内ナビゲーションを優先

提供ツール一覧 (67)

ライフサイクル (5)

browser_launch / browser_connect / browser_disconnect / browser_session_resume / browser_list_sessions

探索 (3)

browser_list_installations / browser_list_running / browser_get_session

タブ (6)

browser_list_tabs / browser_new_tab / browser_activate_tab / browser_close_tab / browser_list_managed_tabs / browser_note_tab

ナビゲーション (6)

browser_navigate / browser_go_back / browser_go_forward / browser_reload / browser_wait_for / browser_wait_for_network_idle

読み取り / キャプチャ (6)

browser_snapshot / browser_snapshot_accessibility / browser_get_element / browser_get_text / browser_get_html / browser_take_screenshot

操作 (10)

browser_click / browser_hover / browser_drag / browser_fill_form / browser_type / browser_press_key / browser_select_option / browser_set_checked / browser_upload_file / browser_scroll

ダイアログ / イベント (6)

browser_get_pending_dialog / browser_dialog_accept / browser_dialog_dismiss / browser_get_console_logs / browser_get_network_logs / browser_eval

ダウンロード (2)

browser_downloads / browser_download_wait

PDF (5)

browser_pdf_open / browser_pdf_viewer_state / browser_pdf_next_page / browser_pdf_prev_page / browser_pdf_extract

Cookie / Storage (4)

browser_get_cookies / browser_set_cookies / browser_storage_get / browser_storage_set

プロファイル (14)

browser_profile_list / browser_profile_get / browser_profile_save / browser_profile_update / browser_profile_rename / browser_profile_clone / browser_profile_validate / browser_profile_dry_run / browser_profile_delete / browser_profile_merge / browser_profile_set_default / browser_profile_get_default / browser_profile_export / browser_profile_import

インストール

git clone https://github.com/cUDGk/mcp-browser-lightpanda.git
cd mcp-browser-lightpanda
npm install
npm run build

Docker Desktop が起動している事、lightpanda/browser:nightly イメージが pull 済みである事が前提。

使い方

claude mcp add mcp-browser-lightpanda -- node C:/path/to/mcp-browser-lightpanda/dist/index.js

環境変数

機能トグル (deny-by-default なものは慎重に開ける事)

変数	既定値	説明
MCP_BROWSER_ALLOW_ATTACH	1	browser_connect を有効化。
MCP_BROWSER_ALLOW_LAUNCH	1	browser_launch を有効化。
MCP_BROWSER_ENFORCE_SINGLE_LAUNCH_SESSION	1	サーバ毎の launch session を 1 個に制限。
MCP_BROWSER_ALLOW_EVAL	0	browser_eval (任意 JS 評価) を許可。RCE 経路扱い。
MCP_BROWSER_ALLOW_FILE_UPLOAD	0	browser_upload_file を許可。MCP_BROWSER_ALLOWED_UPLOAD_ROOTS も必須。
MCP_BROWSER_ALLOW_PRIVATE_NETWORKS	0	127.x / 10.x / 192.168.x 等への navigate / fetch を許可。
MCP_BROWSER_ALLOW_REMOTE_ATTACH	0	browser_connect で loopback 以外の host を許可。
MCP_BROWSER_ALLOW_CROSS_ORIGIN_COOKIES	0	browser_set_cookies で現在タブの eTLD+1 と異なる domain を許可。

制限 / 許容パス

変数	既定値	説明
MCP_BROWSER_ALLOWED_UPLOAD_ROOTS	(空)	path.delimiter 区切りの絶対パス列。browser_upload_file がここ配下のみ受理。
MCP_BROWSER_ALLOWED_READ_ROOTS	upload roots と同じ	browser_pdf_extract の filePath 制限。MCP_BROWSER_ALLOWED_UPLOAD_ROOTS をフォールバック流用。
MCP_BROWSER_PROFILE_EXPORT_DIR	(空)	browser_profile_export/import で読み書きできる追加ディレクトリ。既定では profiles.json のあるディレクトリのみ許可。
MCP_BROWSER_ALLOWED_EXECUTABLE_IMAGES	lightpanda/browser:nightly,lightpanda/browser:*	browser_launch が許可する Docker image (* ワイルドカード可)。

キャップ / バッファサイズ

変数	既定値	説明
MCP_BROWSER_DEFAULT_TIMEOUT_MS	15000	各操作のデフォルトタイムアウト。
MCP_BROWSER_MAX_SNAPSHOT_ELEMENTS	80	snapshot で抽出する要素の上限。
MCP_BROWSER_MAX_TEXT_CHARS	12000	browser_get_text の文字数上限。
MCP_BROWSER_MAX_HTML_CHARS	20000	browser_get_html の文字数上限。
MCP_BROWSER_MAX_EVAL_RESULT_CHARS	4000	browser_eval の戻り値 JSON サイズ上限。
MCP_BROWSER_MAX_EVAL_RESULT_ITEMS	100	browser_eval の戻り値 array 要素数の参考上限 (現状は cap_chars が支配的)。
MCP_BROWSER_MAX_EVAL_EXPRESSION_CHARS	10240	browser_eval の式長上限 (10 KB)。
MCP_BROWSER_MAX_ELEMENT_REFS	5000	element ref のセッション横断上限 (FIFO)。
MCP_BROWSER_MAX_TABS_PER_SESSION	50	session あたり managed tab 上限。
MCP_BROWSER_MAX_SESSIONS	10	プロセスあたり session 上限。
MCP_BROWSER_MAX_PROFILE_FILE_BYTES	5 MiB	profiles.json / import file の上限。
MCP_BROWSER_MAX_PDF_BYTES	200 MiB	browser_pdf_extract の入力サイズ上限。
MCP_BROWSER_MAX_PDF_PAGES	200	browser_pdf_extract の 1 リクエスト最大ページ数。
MCP_BROWSER_DOWNLOAD_MAX_BYTES	1 GiB	ダウンロードファイルの上限。超過すると cancel。

ストレージパス

変数	既定値	説明
MCP_BROWSER_DOWNLOAD_DIR	~/.mcp-browser-lightpanda/downloads	ダウンロード保存先。
MCP_BROWSER_SCREENSHOT_DIR	~/.mcp-browser-lightpanda/screenshots	スクリーンショット保存先。
MCP_BROWSER_TEMP_DIR	~/.mcp-browser-lightpanda/tmp	一時ファイル。
MCP_BROWSER_PROFILES_FILE	~/.mcp-browser-lightpanda/profiles.json	プロファイル DB。
MCP_BROWSER_LOG_LEVEL	info	error / warn / info / debug。

英語版 README

より詳細な設計ノートと制約の説明は README_en.md を参照。

変更履歴

0.1.2 (security & UX hardening)

• SSRF guard: browser_navigate / browser_new_tab / browser_pdf_open / browser_pdf_extract / browser_launch (startupUrl) で file:// / chrome:// / private IP / loopback / .internal を deny。MCP_BROWSER_ALLOW_PRIVATE_NETWORKS=1 で解除。
• path allowlist: browser_pdf_extract.filePath / browser_profile_export.path / browser_profile_import.path / browser_upload_file.filePaths を realpath ベースで MCP_BROWSER_ALLOWED_*_ROOTS に制限。symlink 抜けを潰す。
• Docker hardening: --memory=2g --cpus=2 --pids-limit=512 --security-opt=no-new-privileges --cap-drop=ALL --pull=missing を付与し、CDP ポートを 127.0.0.1 限定で publish。executablePath は image allowlist と照合。
• eval guardrails: 式長 10 KB cap、import()/require()/Function( は静的拒否、Promise.race でデフォルトタイムアウト。
• cookie scope: browser_set_cookies の domain を現在タブの eTLD+1 と一致させる。MCP_BROWSER_ALLOW_CROSS_ORIGIN_COOKIES=1 で解除。
• resource caps: element ref / tab / session / profile file size / download size の上限を導入。
• bug fixes: syncDialogs 全タブ drain (B2)、typeText の clearFirst=false で pressSequentially 追記 (B3)、instrumentPage の二重 listener 防止を WeakSet 化 (B4)、download.path() タイムアウト (B5)、renameProfile / write() を atomic 化 (B12 / B13)、ダイアログ accept/dismiss の finally clear (B15)、get_text / get_html の ELEMENT_NOT_FOUND 明示 (B20)、その他多数。
• UX: 全ツールの JSON-Schema property に description を付け、anyOf/required 制約を追加。browser_get_text / browser_get_html の target shape を共通化。

0.1.1

• 一部 MCP クライアント (Claude Code 等) が object / array 引数を JSON 文字列で渡してくるケースを吸収。

ライセンス

MIT License — 詳細は LICENSE を参照。