Mcp Window Screenshooter

ウィンドウスクリーンショッター MCP サーバー 🖼️

AI エージェントが特定のアプリケーションウィンドウのスクリーンショットを撮影できる、クロスプラットフォーム対応の Model Context Protocol（MCP）サーバーです！（≧◡≦）

概要

Window Screenshooter は、Windows と Linux の各プラットフォームで、特定のアプリケーションウィンドウを対象にスクリーンショットを撮影する機能を AI エージェントに提供する、Python 製の MCP サーバーです。画面全体だけを撮影する従来の画面キャプチャソリューションとは異なり、このサーバーでは、AI による検証ワークフロー、自動テスト、アプリケーションの監視に向けて、ウィンドウを正確に指定してキャプチャできます。

✨ 新機能：ウィンドウ状態のスマートな復元とフォーカス管理！

最新版には、ウィンドウ状態の自動復元とインテリジェントなフォーカス処理が追加されました！🎉

ウィンドウをキャプチャするとき、サーバーは次の処理を行います。

• 📸 元のウィンドウ状態（最小化、最大化、位置など）を保存します
• 🔄 キャプチャに必要な場合、一時的にウィンドウを変更します
• ✨ キャプチャ後にウィンドウを正確に元の状態に復元します
• 🎯 エディター（Cursor、Trae、Windsurf、VS Code など）を自動検出し、そこにフォーカスを戻します
• 📉 呼び出し元のアプリケーションが見つからない場合、キャプチャしたウィンドウを最小化します
• 💫 サポートされているすべてのプラットフォームでシームレスに動作します

これにより、ワークフローがスムーズに保たれます。フォーカスはエディターに戻り、ウィンドウが予期しない状態のままになることはありません！

主な機能

• 🖼️ ウィンドウ単位のキャプチャ：名前またはタイトルで個別のアプリケーションウィンドウを指定します
• 🌐 クロスプラットフォーム対応：プラットフォームに最適化されたバックエンドにより、Windows と Linux で動作します
• 🔧 MCP 統合：Model Context Protocol を通じて AI エージェントとシームレスに連携します
• 📡 STDIO トランスポート：信頼性の高い通信のために標準入出力を使用します
• ⚡ パフォーマンスの最適化：効率を最大限に高めるプラットフォーム固有の実装です

インストールとセットアップ

前提条件

• Python 3.12+
• Windows または Linux

クイックスタート

1. このリポジトリをクローンまたはダウンロードします：

   git clone <your-repo-url>
   cd window-screenshooter
   

2. 依存関係をインストールします：

   pip install pywinctl pillow pywin32
   # Or use the project file
   pip install -e .
   

3. サーバーをテストします：

   python test-mcp.py
   

4. MCP サーバーを実行します：

   # STDIO mode (for MCP clients)
   python server.py
   

MCP ツール

このサーバーは、次の 3 つの主な MCP ツールを公開します。

1. capture_window

タイトルまたは識別子で指定したウィンドウのスクリーンショットを撮影します。

パラメーター：

• windowTitle（string）：一致させるウィンドウのタイトル（完全一致または部分一致）
• outputPath（string、任意）：スクリーンショットの保存先
• format（string、任意）：画像形式（PNG、JPEG）— デフォルト：PNG
• quality（int、任意）：JPEG の画質（1～100）— デフォルト：85

戻り値： Base64 エンコードされた画像データ、またはファイルパスの確認

例：

# Save to file
await capture_window("Notepad", "screenshot.png", "PNG")

# Get base64 data
await capture_window("Calculator")

2. list_windows

システム上で利用可能なすべてのウィンドウを列挙します。

戻り値： ID、タイトル、位置、サイズの情報を含むウィンドウオブジェクトの配列

例：

await list_windows()

3. get_window_info

特定のウィンドウに関する詳細情報を取得します。

パラメーター：

• windowIdentifier（string）：ウィンドウのタイトルまたは ID

戻り値： 位置、サイズ、表示状態、プロセス情報などのウィンドウメタデータ

例：

await get_window_info("Visual Studio Code")

プラットフォーム固有の機能

Windows の実装

• win32gui と BitBlt API を利用した堅牢なウィンドウキャプチャ
• 最小化、非表示、または他のウィンドウに重なったウィンドウもキャプチャできます
• 高性能な Graphics Capture API 統合
• Windows ハンドル（HWND）とプロセス情報を提供します

Linux の実装

• ネイティブプロトコルを使用した X11 ベースのウィンドウキャプチャ
• 効率的なキャプチャを実現するウィンドウバッファへの直接アクセス
• 一般的な Linux デスクトップ環境に対応

MCP クライアントの設定

Cursor IDE の場合

MCP 設定ファイルに追加します。

{
  "mcpServers": {
    "window-screenshooter": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/window-screenshooter",
      "transport": "stdio"
    }
  }
}

Claude Desktop の場合

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "window-screenshooter": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/window-screenshooter"
    }
  }
}

💡 IDE の設定に関するヒント

📝 Note: ワークフローとの連携を最適化するため、次のルールを IDE の設定に追加することを検討してください。

「MCP screenshooter でウィンドウや画面をキャプチャする前に、正しい名前を取得するため、必ず最初にウィンドウの一覧を取得してください。Web プロジェクトで作業している場合、デフォルトのブラウザーは Brave です。Unity プロジェクトで作業している場合、ユーザーが必要としているのは Unity のゲームシーンウィンドウです。スクリーンショットを撮影するか画面をキャプチャした後は、必ずビジョンを使用してください。」

これにより、キャプチャ対象のウィンドウを正確に指定し、キャプチャした内容を適切に分析できます！ ✨

使用例

AI 開発ワークフロー

• コードの検証：AI が Unity エディターのスクリーンショットを撮影し、ゲームオブジェクトの配置を検証します
• UI テスト：自動テストの実行中にアプリケーションの状態をキャプチャします
• ドキュメント作成：アプリケーションのインターフェースを視覚的なドキュメントとして作成します
• デバッグ：アプリケーションの動作変更を視覚的に確認します

自動化のシナリオ

• 品質保証：リグレッションテスト用にスクリーンショットを比較します
• プロセスの監視：ワークフローを検証するため、アプリケーションの状態をキャプチャします
• トレーニングデータ：コンピュータービジョンのトレーニング用にラベル付きのスクリーンショットを生成します

エラー処理

このサーバーでは、次の状況に対応する堅牢なエラー処理を実装しています。

• ウィンドウが見つからない場合
• キャプチャが拒否された場合
• クロスプラットフォームの互換性に関する問題
• 無効なパラメーターの検証
• プラットフォーム固有の機能が利用できない場合の適切な縮退動作

開発とコントリビューション

プロジェクト構成

window-screenshooter/
├── server.py              # Main MCP server implementation
├── windows_capture.py     # Windows-specific capture logic
├── linux_capture.py      # Linux-specific capture logic
├── test-mcp.py           # Test script for functionality
├── mcp-config-example.json # Example MCP configuration
├── pyproject.toml        # Project dependencies
└── README.md            # This file

テスト

テストスクリプトを実行して、機能を検証します。

python test-mcp.py

よくある問題

1. 「ウィンドウが見つかりません」というエラー：

   • list_windows でウィンドウの正確なタイトルを確認してください
   • タイトルの部分一致を試してください
   • ウィンドウが表示されていて、最小化されていないことを確認してください

2. Windows での権限エラー：

   • 必要に応じて、管理者として実行してください
   • Windows のセキュリティ設定を確認してください

3. インポートエラー：

   • すべての依存関係がインストールされていることを確認してください：pip install pywinctl pillow pywin32
   • Python のバージョンを確認してください（3.12 以降が必要です）

プラットフォームの互換性

• Windows：ネイティブ Win32 API による完全なサポート
• Linux：X11 との連携による基本的なサポート

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。