OpenScreenShot

---

クイックスタート

npx openscreenshot shot https://example.com --out example.png --full

ヘッドレス Chrome を起動し、ページを読み込んで、ページ全体の PNG を保存したあと、ブラウザーを閉じます。

必要なもの： Node.js 22.12 以降、および Google Chrome、Chromium、または Microsoft Edge。 このパッケージにはブラウザーが同梱されていないため、インストールサイズは小さく抑えられます。

パッケージマネージャー	1 回だけ実行	グローバルにインストール
npm	npx openscreenshot shot <url>	npm i -g openscreenshot
pnpm	pnpm dlx openscreenshot shot <url>	pnpm add -g openscreenshot
Bun	bunx openscreenshot shot <url>	bun add -g openscreenshot

どこからでも openscreenshot コマンドを使えるようにするには、グローバルにインストールしてください。CI では、代わりにプロジェクトに追加してください（npm i -D openscreenshot）。そうすれば、実行のたびにロックファイルに記載されたバージョンが使われます。

CLI

openscreenshot shot <url> [--out <file>|-] [--full] [--width <n>] [--height <n>]
                    [--redact <selector>]... [--redact-pattern <name>]... [--redact-rect <x,y,w,h>]...
                    [--cloud [<base-url>]] [--key <api-key>] [--format <format>]
openscreenshot auth login [--cloud <base-url>]
openscreenshot auth logout
openscreenshot serve

オプション	デフォルト	説明
<url>	必須	キャプチャするページです。https:// を含む完全な URL を指定してください。
--out <file>	screenshot.png	PNG の出力先です。標準出力にバイト列を書き込むには - を指定します。
--full	オフ	ビューポートだけでなく、スクロール可能なページ全体をキャプチャします。
--width <n>	1280	ビューポートの幅（ピクセル単位）です。200～3840 の範囲で指定します。
--height <n>	800	ビューポートの高さ（ピクセル単位）です。200～2160 の範囲で指定します。
--redact <selector>	なし	CSS セレクターに一致する要素を覆います。複数指定できます。
--redact-pattern <name>	なし	email、phone、secret に一致するテキストを覆います。複数回指定するか、カンマ区切りで指定します。
--redact-rect <x,y,w,h>	なし	出力画像のピクセル単位で指定した矩形領域を覆います。複数指定できます。
--cloud [<base-url>]	オフ	OpenScreenShot Cloud でレンダリングします。Cloud を参照してください。
--key <api-key>	なし	この実行で使用する Cloud API キー（osc_live_…）です。
--format <format>	png	--cloud 使用時の形式です：png、jpeg、webp、pdf、html、または markdown。

使用例

# Full page
openscreenshot shot https://example.com --out page.png --full

# Fixed desktop viewport
openscreenshot shot https://example.com --out desktop.png --width 1440 --height 900

# Narrow viewport to check a responsive layout
openscreenshot shot https://example.com --out narrow.png --width 390 --height 844

# Pipe the PNG to another tool
openscreenshot shot https://example.com --out - > shot.png

# Cover the account menu, every email address, and a 200x40 area at the top left
openscreenshot shot https://example.com --out safe.png --redact "#account-menu" --redact-pattern email --redact-rect 0,0,200,40

仕組みと見逃す可能性があるものについては、マスキングを参照してください。

ローカル出力は常に PNG です。ファイル名を .jpg や .pdf にしても形式は変換されません。他の形式を使用するには、--cloud と --format を指定してください。

ビューポートの幅を狭くすると、レイアウトの幅だけが変わります。CLI はデスクトップのユーザーエージェントを維持するため、スマートフォンのタッチ入力やピクセル比はエミュレートしません。

終了コード

Code	意味
0	ファイルが書き込まれました。
1	キャプチャに失敗しました。たとえば、Chrome が見つからない場合やタイムアウトした場合です。
2	使い方が間違っているか、オプションの範囲外です。

終了コード 0 は、CLI がファイルを保存したことを意味します。ページが正しく読み込まれたことを示すものではないため、エラーページや読み込み中のスピナーがないか画像を確認してください。

MCP サーバー

標準入力がパイプで接続された状態で引数なしの openscreenshot を実行すると、標準入出力を介した Model Context Protocol サーバーが起動します。これは MCP クライアントが実行する方法です。openscreenshot serve も同じように動作し、既存の設定で起動します。AI クライアントはこれをローカルプロセスとして起動するため、入力する URL はありません。

クライアントへの追加

mcpServers オブジェクトを使用するクライアント（Claude Desktop、Cursor、Windsurf など）：

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

Claude Code：

claude mcp add openscreenshot -- npx -y openscreenshot

設定を保存した後、クライアントを再起動するか、再読み込みしてください。クライアントが PATH 上の npx（または pnpm、bunx）を見つけられる必要があります。

ツール：capture_screenshot

入力	型	デフォルト	備考
url	string	—	必須です。ページの完全な URL を指定します。
fullPage	boolean	false	ページ全体をキャプチャします。
width	integer	1280	200～3840。
height	integer	800	200～2160。
redact	object	—	任意です。以下を参照してください。
cloud	boolean	false	Cloud 上でレンダリングします。Cloudを参照してください。

{ "url": "https://example.com", "fullPage": true, "width": 1440, "height": 900 }

redact には、任意のリストが 3 つあります。

フィールド	型	対象
selectors	string[]	各 CSS セレクターに一致する要素。
patterns	("email" | "phone" | "secret")[]	ページ内およびフォーム値内の一致するテキスト。
rects	{ x, y, width, height }[]	出力画像のピクセル単位の矩形。

{
  "url": "https://example.com",
  "redact": {
    "selectors": ["#account-menu"],
    "patterns": ["email", "secret"],
    "rects": [{ "x": 0, "y": 0, "width": 200, "height": 40 }]
  }
}

このツールは PNG を MCP の画像コンテンツ（image/png）として返します。ファイルは書き込みません。名前を付けてファイルを保存するには、CLI を使用してください。

マスキング

マスキングでは、ページ内の対象に黒いボックスを重ねてから、スクリーンショットを撮影します。マスキングされていないピクセルが PNG に含まれることはないため、MCP クライアントやホストされたモデルに渡ることもありません。

• セレクター。 ボックスは要素とそのすべての子要素を覆います。セレクターに一致する要素がない場合、または有効な CSS ではない場合、キャプチャは失敗します。
• パターン。 email はメールアドレスを検出します。phone は 9～15 桁の数字を検出します。secret は、一般的な API キーやトークンの形式（OpenAI、Anthropic、Stripe、GitHub、AWS、Slack、Google、JWT）を検出します。また、ハッシュなど、英字と数字を含む 32 文字以上の英字、数字、アンダースコアの連続も検出します。 パターンはテキストと、input、textarea、select フィールドの値を検索します。
• 矩形。 セレクターやパターンでは検索できない canvas、画像、クロスオリジンの iframe に使用します。画像の完全に外側にある矩形を指定すると、キャプチャは失敗します。

マスキングが有効な場合、ツールは CSS アニメーションを一時停止し、ボックスを配置してからスクリーンショットを撮影します。その後、対象を再度検索します。対象がボックスの外に移動していた場合、キャプチャは失敗します。キャプチャに失敗するとファイルは書き込まれず、画像も返されません。

パターンでテキストを検出できないことがあります。要素に分割されたテキスト、canvas や画像に描画されたテキスト、認識できない形式のテキストは検出されません。また、一致したように見えるだけのテキストが覆われることもあります。共有する前に画像を確認してください。

キャプチャできるもの、できないもの

キャプチャごとに、プロファイルが空の新しいヘッドレスブラウザーが起動します。

• キャプチャできるもの： ログアウト状態の訪問者が閲覧できるページです。公開サイト、ドキュメント、ステータスページ、ステージング環境のビルド、localhost の開発サーバーが含まれます。
• キャプチャできないもの： Cookie やログイン済みセッションは参照できません。ログインが必要なページでは、ログイン画面が表示されます。
• 実行しないこと： クリック、入力、セレクターの待機、Cookie の設定は行いません。ナビゲーションでは、最大 30 秒間、ネットワークが静かになるまで待機します（networkidle2）。

ログインが必要なページ、注釈、PDF エクスポートには、Chrome および Firefox 用の OpenScreenShot ブラウザー拡張機能を使用してください。

OpenScreenShot Cloud（任意）

OpenScreenShot Cloud は、ホスト型のスクリーンショット API です。Cloud サーバーでページをレンダリングするため、マシンに Chrome を用意する必要はありません。ローカルモードがデフォルトで、アカウントは不要です。

無料プランでは月 100 回までキャプチャでき、カードの登録は不要です。キャプチャに失敗した場合、料金はかかりません。有料プランについては料金ページをご覧ください。

サインイン

openscreenshot auth login

このコマンドは ABCD-EFGH のようなコードを表示し、ブラウザーで https://cloud.openscreenshot.app/device を開きます。Cloud からメールで届くコードを使ってサインインし、そのコードを承認してください。CLI はその後、API キーを ~/.openscreenshot.json に保存します。別の Cloud ベース URL を使用するには、--cloud <url> を追加します。openscreenshot auth logout を実行すると、保存されたキーが削除されます。

CLI からの Cloud の利用

# Full-page PNG, rendered on Cloud
openscreenshot shot https://example.com --out page.png --full --cloud

# PDF of the page
openscreenshot shot https://example.com --out page.pdf --cloud --format pdf

--format では、png、jpeg、webp、pdf、html、markdown を指定できます。--full、--width、--height はローカルモードと同様に機能します。

CLI は、最初に見つかった API キーを使用します。

1. --key osc_live_…
2. OPENSCREENSHOT_API_KEY 環境変数
3. auth login で保存したキー

ベース URL は、--cloud <url>、OPENSCREENSHOT_CLOUD_URL、https://cloud.openscreenshot.app の順に使用されます。

--redact、--redact-pattern、--redact-rect は --cloud と併用できます。Cloud サーバーは画像を返す前に黒いボックスを描画します。マスキングには PNG 出力が必要です。ローカルモードと同様に、何にも一致しないセレクターを指定するとキャプチャは失敗し、画像は返されません。

MCP から Cloud を使用する

capture_screenshot に cloud: true を設定すると、Cloud でレンダリングできます。

{ "url": "https://example.com", "fullPage": true, "cloud": true }

サーバーには、openscreenshot auth login で取得したキー、またはサーバーの env ブロックに設定した OPENSCREENSHOT_API_KEY が必要です。redact はどちらのモードでも機能します。

Cloud は、リモート MCP URL のみを受け付けるクライアント向けに、Streamable HTTP 経由のリモート MCP エンドポイントも提供します。

• URL：https://cloud.openscreenshot.app/mcp
• ヘッダー：Authorization: Bearer <api-key>
• ツール：capture_screenshot

Cloud モードでのプライバシー

--cloud または cloud: true を指定すると、URL とオプションが OpenScreenShot Cloud に送信され、ページは Cloud サーバー上でレンダリングされます。Cloud のプライバシーポリシーをご確認ください。 ローカルモードでは、OpenScreenShot に何も送信されません。

Cloud API ドキュメントには、すべてのオプションが記載されています。

ユースケース

• CI/CD： リリースノート、ドキュメント、ビジュアルレビュー用に、デプロイのたびにページをキャプチャします。 CI ガイドをご覧ください。
• DevOps： cron またはチャットコマンドから、ダッシュボードやステータスページをインシデントレポートやランブックにスナップショットとして保存します。
• AI エージェント： エージェントが直前に作成または変更したページを確認できるようにします。

トラブルシューティング

Chrome not found。 CLI は、macOS、Linux、Windows の標準インストールパスを確認します。ブラウザーが別の場所にある場合は、実行ファイルを指すように CHROME_PATH を設定してください。

CHROME_PATH=/usr/bin/chromium openscreenshot shot https://example.com

Windows では、ユーザーごとにインストールされた Chrome は %LOCALAPPDATA% の下にあり、Edge は確認されません。両方とも CHROME_PATH を設定してください。MCP クライアントでは、サーバーの env ブロックに CHROME_PATH を設定してください。

引数なしの openscreenshot でスクリプトがハングする。 引数なしで、標準入力がパイプ接続されている場合、このコマンドは MCP サーバーを起動し、クライアントを待機します。その旨を示す1行を標準エラー出力に表示します。キャプチャするには openscreenshot shot <url> を実行してください。

タイムアウト。 30秒以内にページの動作が落ち着きませんでした。ロングポーリングまたはストリーミング接続を使うページで発生することがあります。

画像が空白、または読み込みが不完全。 ネットワークが落ち着いた後にレンダリングされるページもあります。CLI には、まだ追加の待機オプションがありません。

プライバシーとセキュリティ

• ローカルモードでは、すべての処理がご利用のマシン上で実行されます。このパッケージはテレメトリーを送信せず、OpenScreenShot サーバーにも接続しません。OpenScreenShot Cloud に接続するのは、auth login、--cloud、または cloud: true を使用する場合のみです。
• MCP モードでは、クライアントが画像を受け取ります。クライアントがホスト型モデルを使用している場合、そのモデルのプロバイダーに画像を送信することがあります。画像がツールから外部に送信される前に、redact を使用してデータを隠してください。
• ヘッドレスブラウザーは、コンテナーや CI で動作するように --no-sandbox を指定して実行されます。信頼できる URL のみをキャプチャしてください。

リンク

• ソース：PGHQdev/OpenScreenShot の mcp/
• ブラウザー拡張機能：Chrome ウェブストア · Firefox Add-ons
• プロジェクトを支援：ko-fi.com/pghqdev

MIT © OpenScreenShot @PGHQdev