MCP Test Utils

MCP Test Utils

デスクトップ UI テストを自動化する MCP サーバーです。単一のバイナリで動作し、ランタイム、依存関係、インストーラーは不要です。

Windows x64 のみ対応しています。 macOS 版と Linux 版はまだありません。必要な場合は、 [email protected] までご連絡ください。次に何を作るかはリクエスト次第です。

スクリーンショット、ウィンドウ管理、マウス、キーボード、UI Automation、OCR、ファイル検索を通じて、AI エージェントに目と手を与えます。 保存済みのシナリオを回帰テストとして再生し、ビルドのたびにエージェントなしで実行できます。操作を記録してドラフトシナリオを作成し、アクセシビリティを確認し、テスト対象アプリケーションのリソースを監視します。

理由

AI エージェントはアプリケーション内で操作を実行できますが、画面を見ることはできません。このサーバーがそのギャップを埋めます。

Agent triggers action → takes screenshot → sees the result →
switches window → clicks a button → verifies → writes report

ユーザーの関与なしに、完全自律で実行できます。

デモ

3.26 — シナリオ実行 Claude が保存済みテストを再生：232ステップ、1回の呼び出し、66秒

インストールとセットアップ サーバーと基本ツールのセットアップ

セットアップ

1. Releases から mcp-test-utils.exe をダウンロードします（隣にある .sig ファイルは組み込みアップデーター用です。不要です）。
2. MCP クライアントに追加します。

Claude Desktop： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "test-utils": {
      "command": "D:\\path\\to\\mcp-test-utils.exe"
    }
  }
}

Claude Code：

claude mcp add test-utils -- "D:\path\to\mcp-test-utils.exe"

その他のクライアントについては、それぞれのドキュメントを参照してください。

3. クライアントを再起動します。
4. チャットで 「スクリーンショットを撮って」 と試してみてください。エージェントがデスクトップの画像を返します。

ログ記録、ファイル検索、プログラムの起動などのオプション設定は env に指定します。環境変数を参照してください。

{
  "mcpServers": {
    "test-utils": {
      "command": "D:\\path\\to\\mcp-test-utils.exe",
      "env": {
        "MCP_LOG_DIR": "D:\\path\\to\\logs",
        "MCP_SEARCH_DIRS": "D:\\Projects\\app1;D:\\Projects\\app2",
        "MCP_LAUNCH_APPS": "C:\\Program Files\\MyApp\\myapp.exe"
      }
    }
  }
}

ツール（31）

設定時のみ表示されるツールが4つあります。MCP_SEARCH_DIRS を設定すると search_in_files と find_files が、MCP_LOG_DIR を設定すると enable_logging と disable_logging が表示されます。デフォルトでは、サーバーは27個のツールを一覧表示します。

ビジョン

ツール	説明
take_screenshot	デスクトップ全体のスクリーンショット。フルから最小（トークン数が少ない）までの品質プリセットがあります
take_window_screenshot	特定のウィンドウのスクリーンショット
read_screen_text	画面全体をOCRで読み取ります（Windows OCR）
read_region_text	画面の領域を、正確な単語座標とともにOCRで読み取ります

ウィンドウ管理

ツール	説明
list_windows	ID、タイトル、アプリ、プロセス ID、位置、サイズ、状態を含むウィンドウ一覧
focus_window	ウィンドウを前面に表示し、最小化されている場合は元に戻します。位置とサイズも任意で設定できます
launch_app	サーバー設定の許可リスト（MCP_LAUNCH_APPS）にあるプログラムを起動し、そのウィンドウが表示されるまで待機します
close_window	ウィンドウの X ボタンを押した場合と同様にウィンドウを閉じ、消えるまで待機します。「変更を保存しますか？」というプロンプトも報告します

入力

ツール	説明
mouse_click	ID または座標で要素をクリックします（左／右／中央、ダブルクリック）。期待する効果を待って再試行できます
mouse_move	カーソルをポイントまたは UI 要素に移動します
mouse_drag	人間の速度で要素間またはポイント間をドラッグします（HTML5 のドラッグ＆ドロップにも対応）
mouse_scroll	要素上でマウスホイールをスクロールし、スクロールが止まるまで待機します
keyboard_type	テキストを入力します（完全な Unicode に対応 — ラテン文字、キリル文字、CJK、絵文字）。入力欄に入力内容が表示されていることを確認します
keyboard_press	キーを押します（Enter、Tab、F1–F12、矢印キーなど）。複数回押すこともできます
keyboard_shortcut	キーの組み合わせを押します（Ctrl+S、Alt+F4、Ctrl+Shift+P など）

構造化 UI アクセス

ツール	説明
list_ui_elements	UI Automation ツリー — ボタン、フィールド、メニューの ID、値、状態、正確な座標を表示します。名前、値、クラスでフィルタリングできます
get_focused_element	現在キーボードフォーカスがある要素と、そのウィンドウを確認します
read_text	UI Automation を通じてドキュメントまたはフィールドの全文を読み取ります（1 回の呼び出しにつき最大 100 000 文字）。OCR は使用しません
ui_action	マウスやキーボードを使わずに要素を操作します。呼び出し、切り替え、展開、オプションの選択、値の設定、表示範囲へのスクロールができます
check_accessibility	アクセシビリティ上の欠陥を確認します。名前のないコントロール、Tab キーでフォーカスできないコントロール、重複した ID、サイズがゼロのコントロールなど

プロセス

ツール	説明
process_info	テスト対象アプリのメモリ、ハンドル、GDI オブジェクト、スレッド、CPU を確認します。リークを検出するために繰り返し呼び出してください

待機、バッチ処理、シナリオ

ツール	説明
wait_for	スリープの代わりに、ウィンドウ、要素、またはその状態を待ちます
batch	find および assert ステップを含む最大 20 件のツール呼び出しを 1 回のリクエストで実行します
run_scenario	保存済みのシナリオ、スイート、またはデータ行を再生し、合否レポートを取得します（エージェントなしでの回帰テストを参照）
record_scenario	1 つのウィンドウでの操作をドラフトシナリオに記録します（記録を参照）

ファイル検索

ツール	説明
search_in_files	許可されたディレクトリ内のファイルで、テキストまたは正規表現を検索します（VS Code の「ファイル内を検索」のように動作します）
find_files	「ファイルへ移動」のように、名前パターン（glob）でファイルやディレクトリを検索します

エージェントガイド

ツール	説明
get_usage_guide	エージェント向けの使用ガイドです。基本ルールと、リクエストに応じたセクションを提供します
prepare_feedback	作成者向けの提案ファイルを準備します（個人データはマスキングされます。内容を確認してメールで送信してください。自動送信はされません）

セッションのログ記録

ツール	説明
enable_logging	ツール呼び出しを JSONL とスクリーンショットに記録し始めます（オプトイン）
disable_logging	記録を停止し、セッション統計を取得します

エージェントなしでの回帰テスト

エージェントはアプリケーション内の経路を一度たどって、シナリオ（JSON ファイル）として保存します。その後はエージェントなしでシナリオを再生でき、毎回同じように高速に実行でき、トークンも消費しません。

mcp-test-utils --check order-form.json     # validate the file, touch nothing
mcp-test-utils --run order-form.json       # run: report in the console and in order-form.report.json

• 終了コード：0 — 成功、1 — ステップ失敗、2 — 未実行です。各ビルド後の CI ジョブですぐに使用できます。
• 失敗すると、スクリーンショット、要素ツリー、ヒントが表示されます。シナリオが古くなっているか、アプリケーションが変更された可能性があります。
• エージェントは run_scenario(path) でシナリオを実行し、get_usage_guide(section: "scenarios") で形式を確認します。
• スイートとデータ行： --suite は複数のシナリオファイルを順番に実行し、1 つの概要を表示します。--data rows.csv はシナリオを各行につき 1 回実行します（列は変数になります）。--junit report.xml は CI 用の JUnit XML を追加します。

  mcp-test-utils --suite regress.suite.json --junit regress.xml
  

• ライセンスキーがない場合、シナリオは最大 50 ステップまで実行されます（ライセンスキーを参照）。

Recording

手順を自分で実行してエージェントに説明する代わりに、シナリオのドラフトを作成します：

mcp-test-utils --record order-form.json --app myapp

そのウィンドウとダイアログだけが録画され、画面に通知が表示されます。Ctrl+Alt+Shift+R（またはコンソールで Enter）を押すと録画が停止します。パスワード欄が読み取られることはありません。ターミナルに入力したテキストが録画されるのは、--keys-text を指定した場合だけです。エージェントは record_scenario で同じ録画を開始できます。

環境変数

変数	説明	デフォルト
MCP_LOG_DIR	ログセッションの保存先。設定しない場合、ログ記録ツールは非表示になります	—
MCP_LOG_MAX_MB	セッションのサイズ上限（超過時に警告）	500
MCP_LOG_RETAIN_DAYS	N 日より古いセッションを自動削除します。無効にするには 0 を指定します	30
MCP_SEARCH_DIRS	search_in_files と find_files で許可するディレクトリ（; 区切り）。設定しない場合、どちらも非表示になります	—
MCP_LAUNCH_APPS	launch_app で起動できるプログラム（.exe ファイルまたはフォルダー、; 区切り）。シェル、スクリプトホスト、インタープリターは、一覧に含まれていても起動できません。設定しない場合、launch_app は何も起動しません	—
MCP_NOTIFY	off にすると、タスクトレイアイコンとリアルタイムの呼び出しログウィンドウが非表示になります	—
MCP_INPUT_LOCK	off にすると、サーバーが入力を送信する間のキーボードとマウスのロックが無効になります	—
MCP_INPUT_LOCK_STALL_MS	ロックが入力を解放するまでの、サーバーからの応答がない時間（ミリ秒）	60000

タスクトレイアイコン、更新、入力ロック

• タスクトレイアイコンにはツール呼び出しのリアルタイムログが表示されます。セッションごとにタブがあり、エラーは赤色で表示されます。MCP_NOTIFY=off にすると非表示になります。
• 更新： タスクトレイメニュー → 更新を確認…。作成者の署名があるリリースのみがインストールされます。インストール後、MCP クライアントを再起動してください。サーバーがオンラインになるのは、クリックした場合のみです。
• 入力ロック： サーバーがキー入力やクリックを行っている間、キーボードとマウスボタンは一時停止します（ポインターは動きます）。Esc を押すと操作を停止して、入力できる状態に戻ります。MCP_INPUT_LOCK=off にするとロックが無効になります。

フィードバック

エージェントがツールの不足に気づくと、短い提案ファイルの作成を提案します（prepare_feedback）。ファイルは Documents\mcp-test-utils feedback\ に保存され、個人データはマスキングされ、スクリーンショットは含まれません。内容を確認して、[email protected] にメールで送信してください。自動送信されることはありません。

ユースケース

• 自動 QA — エージェントがアプリを操作し、画面遷移を順にクリックして、各手順のスクリーンショットを撮り、テストレポートを作成します
• リグレッションテスト — エージェントを使わず、スクリプトまたは CI ジョブから、ビルドごとに保存済みのシナリオを再生します
• 録画テスト — 一度自分で操作してシナリオのドラフトを作成し、エージェントにテストへ変換させます
• デスクトップ自動化 — フォームへの入力、ウィンドウ間のデータコピー、ワークフローの実行
• アクセシビリティ監査 — check_accessibility は、名前のないコントロール、Tab キーで移動できないコントロール、重複した ID を検出します
• リソースリーク — process_info で、呼び出しを繰り返すごとにハンドル数と GDI オブジェクト数が増加しているかを確認します
• 視覚的なチェック — エージェントがビルド間のスクリーンショットを比較します
• データ抽出 — UI Automation を通じてドキュメントのテキストを読み取るか、テキストを公開しないアプリケーションから OCR でテキストを読み取ります
• コード検索 — エージェントのセッションを離れずに、複数のプロジェクトからパターンを検索します

セキュリティ

• MCP クライアントからのリクエストにのみ応答します。ネットワークポートは開きません
• ファイルに書き込むのは、要求された場合のみです。ログ、シナリオレポート、JUnit ファイル、記録した下書き、封印済みシナリオ、フィードバックファイル、ライセンスファイルに加え、%LOCALAPPDATA%\mcp-test-utils\ 内の小さな設定ファイルと、インストールするアップデートが対象です
• 外部にデータを送信しません。トレイウィンドウで「Check for updates」（および「Download and install」）をクリックした場合のみオンラインに接続します。エージェントのツール呼び出しで接続することはありません。また、作成者が署名したファイルのみをインストールします
• 入力を送信する呼び出し、batch、またはシナリオの実行中のみ、キーボードとマウスのボタンを押した状態にします — Esc を押すと、すぐに解除されます
• MCP_LAUNCH_APPS に指定したプログラムのみを起動します（シェルやインタープリターは起動しません）。強制的な close_window で終了するのは、自身が起動したプログラムのみです
• 明示的なコマンドがあった場合のみ記録します。記録中は画面に通知を表示し続け、パスワード欄は読み取りません
• スクリーンショットは画面全体を撮影します — 機密情報が表示されていないことを確認してください
• ファイル検索はサンドボックス化されています — MCP_SEARCH_DIRS 内のディレクトリのみアクセスできます

仕組み

MCP Test Utils は stdin/stdout 経由で動作する MCP サーバーです。MCP クライアントが実行ファイルを起動し、そのツールを呼び出します。ネイティブの Windows API（UI Automation、Win32 入力、Windows OCR）を使用し、PowerShell、補助ツール、ネットワークアクセスは使用しません。ただし、自分で開始するアップデート確認を除きます。Claude Desktop と Claude Code でテスト済みです。

ライセンスキー

すべてのツールは無料です。ライセンスキーで解除できるのは、シナリオ実行の 50 ステップ制限のみです。

現在、キーは早期アクセスを通じて発行しています。最初の 30 名には、初月終了後に簡単なフィードバックをお送りいただくことを条件に、1 年間有効なキーを無料で発行します。メールアドレスとコンピューターのマシンコードを添えて、[email protected] までご連絡ください。キーはそのコンピューターに紐付けられます。エージェントは get_usage_guide の 2 行目でコードを確認できます。自分で表示することもできます。

mcp-test-utils --machine-id

そのコンピューターでキーを一度だけ登録してください。

mcp-test-utils --set-license <email> <key>

Windows を再インストールしたり、マザーボードのみを交換したりしても、キーは有効なままです。新しいコンピューターでは新しいキーが必要です。もう一度ご連絡ください。

封印済みシナリオは、制限なくどこでも実行できます。ただし、そのファイルのみが対象で、封印時の内容と完全に一致している必要があります。 ライセンスを登録したコンピューターで mcp-test-utils --seal order-form.json を実行すると、ファイルに封印を書き込みます。その後、キーを持たない CI エージェントや同僚でも、シナリオを最後まで実行できます。ステップ（または含まれるファイル）を変更すると封印が無効になるため、ライセンスを登録したコンピューターでもう一度封印してください。

サポート

役に立った場合は、jeenyjai.github.io をご覧ください。

ライセンス

著作権 2026 JeenyJAI。All rights reserved。

---

🚀 Claude で作成