MCP Screenshot Server

Universal Screenshot MCP

AI アシスタントにスクリーンショット機能を提供するMCP（Model Context Protocol）サーバーです。Puppeteerによるウェブページのキャプチャと、ネイティブ OS ツールを使用したクロスプラットフォームのシステムスクリーンショットに対応しています。

特長

• ウェブページのスクリーンショット — ヘッドレス Chromium ブラウザーを使用して、公開 URL をキャプチャします
• クロスプラットフォームのシステムスクリーンショット — ネイティブ OS ツールを使用して、全画面、ウィンドウ、または領域をキャプチャします（macOS screencapture、Linux maim／scrot／gnome-screenshot など、Windows PowerShell+.NET）
• セキュリティを最優先した設計 — SSRF 防止、パストラバーサル保護、DNS リバインディング対策、コマンドインジェクション防止、DoS 制限に対応
• MCP ネイティブ — Claude Desktop、Cursor、および MCP 対応のあらゆるクライアントと直接連携します

要件

• Node.js >= 18.0.0
• Chromium は初回実行時に Puppeteer によって自動的にダウンロードされます

take_system_screenshot のプラットフォーム別要件

プラットフォーム	必要なツール	備考
macOS	screencapture（標準搭載）	追加のインストールは不要です
Linux	次のいずれか：maim、scrot、gnome-screenshot、spectacle、grim、または import（ImageMagick）	全機能のサポートには maim または scrot を推奨します。ウィンドウ名でキャプチャするには、xdotool もインストールしてください。
Windows	powershell（標準搭載）	.NET の System.Drawing を使用するため、追加のインストールは不要です

Linux のインストール例

# Ubuntu/Debian (recommended)
sudo apt install maim xdotool

# Fedora
sudo dnf install maim xdotool

# Arch Linux
sudo pacman -S maim xdotool

# Wayland (Sway, etc.)
sudo apt install grim

インストール後、次のコマンドでセットアップを確認できます。

npx universal-screenshot-mcp --doctor

ホストを調査し、検出されたディストリビューションに合わせて、不足しているツールのコピペ可能なインストールコマンドを表示します。

クイックスタート

npm からインストール

npm install -g universal-screenshot-mcp

または、npx で直接実行します。

npx universal-screenshot-mcp

ソースからインストール

git clone https://github.com/sethbang/mcp-screenshot-server.git
cd mcp-screenshot-server
npm install
npm run build

MCP クライアントの設定

MCP クライアントの設定にサーバーを追加します。Claude Desktop の場合は、~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "screenshot-server": {
      "command": "npx",
      "args": ["-y", "universal-screenshot-mcp"]
    }
  }
}

ソースからインストールした場合は、次のように設定します。

{
  "mcpServers": {
    "screenshot-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-screenshot-server/build/index.js"]
    }
  }
}

Claude Code の場合は、claude mcp add コマンドでサーバーを登録します。

# Project scope (current directory only)
claude mcp add screenshot-server -- npx -y universal-screenshot-mcp

# User scope (available across all projects)
claude mcp add --scope user screenshot-server -- npx -y universal-screenshot-mcp

ソースからインストールした場合は、次のように登録します。

claude mcp add screenshot-server -- node /absolute/path/to/mcp-screenshot-server/build/index.js

claude mcp list でサーバーが登録されたことを確認するか、セッション内で /mcp を実行して現在のステータスを確認してください。

Cursor またはその他の MCP クライアントの場合は、同等の設定方法について各クライアントのドキュメントを参照してください。

ツール

このサーバーは、2 つの MCP ツールを公開します。

take_screenshot

ヘッドレス Puppeteer ブラウザーを使用して、ウェブページ（または特定の要素）をキャプチャします。

パラメーター	型	必須	説明
url	string	✅	キャプチャする URL（http／https のみ）
width	number	—	ビューポートの幅（1～3840）
height	number	—	ビューポートの高さ（1～2160）
fullPage	boolean	—	スクロール可能なページ全体をキャプチャします
selector	string	—	特定の要素をキャプチャする CSS セレクター
waitForSelector	string	—	キャプチャ前にこのセレクターが表示されるまで待機します
waitForTimeout	number	—	ミリ秒単位の待機時間（0～30000）
outputPath	string	—	出力ファイルのパス（既定値：~/Documents/screenshots）

プロンプトの例：

https://example.com を 1920x1080 でスクリーンショットに撮ってください

take_system_screenshot

ネイティブ OS ツールを使用して、デスクトップ、特定のアプリケーションウィンドウ、または画面領域をキャプチャします。macOS、Linux、Windowsで動作します。

パラメーター	型	必須	説明
mode	enum	✅	fullscreen、window、または region
windowId	number	—	ウィンドウモードで使用するウィンドウ ID
windowName	string	—	ウィンドウモードで使用するアプリ名（例："Safari"、"Firefox"）
region	object	—	リージョンモードで使用する { x, y, width, height }
display	number	—	マルチモニター環境で使用するディスプレイ番号
includeCursor	boolean	—	キャプチャにマウスカーソルを含めるかどうか
format	enum	—	png（デフォルト）または jpg
delay	number	—	キャプチャまでの遅延時間（秒）（0～10）
outputPath	string	—	出力ファイルパス（デフォルト：~/Documents/screenshots）

クロスプラットフォームの機能サポート

機能	macOS	Linux	Windows
全画面	✅	✅	✅
リージョン	✅	✅ (maim, scrot, grim, import)	✅
名前によるウィンドウ指定	✅	⚠️ X11 + xdotool	⚠️ ベストエフォート
ID によるウィンドウ指定	✅	✅ X11 のみ	⚠️ HWND
マルチディスプレイ	✅	⚠️ ツールに依存	✅
カーソルを含める	✅	⚠️ ツールに依存	⚠️
遅延	✅	✅	✅

プロンプトの例：

Safari のウィンドウのシステムスクリーンショットを撮影してください

設定

環境変数

変数	デフォルト	説明
SCREENSHOT_OUTPUT_DIR	Documents/screenshots	~ を基準とするデフォルトの出力ディレクトリ
ALLOW_LOCAL	false	localhost/127.x.x.x/[::1] のスクリーンショット撮影を許可するには、true に設定します（ローカル開発サーバーで便利です）

出力ディレクトリ

スクリーンショットはデフォルトで ~/Documents/screenshots に保存されます（SCREENSHOT_OUTPUT_DIR で設定可能）。カスタム出力パスは、次の許可されたディレクトリのいずれかに解決される必要があります。

ディレクトリ	説明
~/Documents/screenshots	デフォルトの出力場所（設定可能）
~/Desktop/Screenshots	元のデフォルトの場所
~/Downloads	ユーザーのダウンロードフォルダー
~/Documents	ユーザーのドキュメントフォルダー
/tmp	システムの一時ディレクトリ

セキュリティ

このサーバーでは、複数層のセキュリティ強化を実施しています。

ID	脅威	軽減策
SEC-001	SSRF / DNS リバインディング	URL をブロック対象の IP 範囲に照らして検証します。リクエスト前に DNS を解決し、--host-resolver-rules による IP ピンニングを行います。ナビゲーションのリダイレクトも再検証します
SEC-003	コマンドインジェクション	すべてのサブプロセスで execFile を使用します（シェルは使用しません）。アプリ名は SAFE_APP_NAME_PATTERN に照らして検証します
SEC-004	パストラバーサル	出力パスは fs.realpath() によるシンボリックリンク解決を用いて検証し、許可されたディレクトリに制限します
SEC-005	サービス拒否	セマフォを使用して、Puppeteer の同時実行インスタンスを 3 つに制限します

詳細については、docs/security.md を参照してください。

開発

スクリプト

コマンド	説明
npm run build	TypeScript をコンパイルして build/ に出力します
npm run watch	ファイルの変更時に再コンパイルします
npm test	単体テスト（高速、すべてモックを使用）
npm run test:integration	統合テスト（実際の DNS／ファイルシステムを使用）
npm run test:e2e	E2E テスト（実際の Puppeteer／ネイティブツールを使用）
npm run test:all	すべてのテスト階層をまとめて実行
npm run test:linux	Docker を使用した Linux E2E テスト（Docker が必要）
npm run test:watch	ウォッチモードでテストを実行
npm run test:coverage	カバレッジレポート付きでテストを実行
npm run lint	ESLint でソースを静的解析します
npm run inspector	デバッグ用に MCP Inspector を起動します

プロジェクト構成

src/
├── index.ts                 # Entry point — stdio transport
├── server.ts                # MCP server factory
├── config/
│   ├── index.ts             # Static constants (limits, allowed dirs)
│   └── runtime.ts           # Singleton semaphore, default directory
├── tools/
│   ├── take-screenshot.ts   # Web page capture tool
│   └── take-system-screenshot.ts  # macOS system capture tool
├── types/
│   └── index.ts             # Shared TypeScript interfaces
├── utils/
│   ├── helpers.ts           # Response builders, file utilities
│   ├── screenshot-provider.ts # Cross-platform provider interface + factory
│   ├── macos-provider.ts    # macOS: screencapture wrapper
│   ├── linux-provider.ts    # Linux: maim/scrot/gnome-screenshot/etc.
│   ├── windows-provider.ts  # Windows: PowerShell + .NET System.Drawing
│   ├── macos.ts             # Window ID lookup via CoreGraphics
│   └── semaphore.ts         # Async concurrency limiter
└── validators/
    ├── path.ts              # Output path validation (SEC-004)
    └── url.ts               # URL/SSRF validation (SEC-001)

テスト

テストには Vitest を使用し、次の 3 階層で実施します。

• 単体（npm test） — 依存関係をすべて注入し、実際の I/O は行いません。素早くフィードバックを得られます。
• 統合（npm run test:integration） — 実際の DNS 解決、一時ディレクトリを使った実際のファイルシステム、ローカル HTTP サーバーに接続する実際の Puppeteer を使用します。
• E2E（npm run test:e2e） — 実際のネイティブスクリーンショットツールを使用します。macOS のテストはネイティブ環境で実行し、Linux のテストは npm run test:linux を使用して Docker 内で実行します。

npm test                 # Unit tests (~300ms)
npm run test:linux       # Linux provider tests in Docker
npm run test:all         # Everything

MCP Inspector を使ったデバッグ

npm run inspector

これにより、ビルド済みのサーバーに接続された MCP Inspector が起動し、ツールを対話形式で呼び出せるようになります。

ライセンス

Apache-2.0 — Copyright 2026 Seth Bang