MCPControl

MCPControl

Model Context Protocol 向けの Windows 制御サーバーです。マウス、キーボード、ウィンドウ管理、画面キャプチャ機能など、システム操作をプログラムから制御できます。

注：このプロジェクトは現在、Windows のみをサポートしています。

🔥 MCPControl を選ぶ理由

MCPControl は AI モデルとデスクトップをつなぎ、次の操作を安全にプログラムから実行できるようにします。

• 🖱️ マウスの移動とクリック
• ⌨️ キーボード入力とショートカット
• 🪟 ウィンドウ管理
• 📸 画面キャプチャと分析
• 📋 クリップボード操作

🔌 クイックスタート

前提条件

1. ビルドツールをインストール（VC++ ワークロードを含む）

   # Run as Administrator - may take a few minutes to complete
   winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
   

2. Python をインストール（まだインストールされていない場合）

   # Install Python (required for node-gyp)
   winget install Python.Python.3.12
   

3. Node.js をインストール

   # Install latest LTS version
   winget install OpenJS.NodeJS
   

インストール

1. MCPControl パッケージをインストール

   npm install -g mcp-control
   

設定

MCPControl は、クリック精度を最適化するため、解像度 1280x720 の仮想マシンでの使用に最適化されています。

SSE トランスポート経由で MCPControl に接続するように、Claude クライアントを設定します。

オプション 1：SSE による直接接続

VM またはリモートマシンで実行中の MCPControl サーバーに接続する場合：

{
  "mcpServers": {
    "MCPControl": {
      "transport": "sse",
      "url": "http://192.168.1.100:3232/mcp"
    }
  }
}

192.168.1.100:3232 をサーバーの IP アドレスとポートに置き換えてください。

オプション 2：SSE によるローカル起動

SSE トランスポートを使用して MCPControl をローカルで起動する場合：

{
  "mcpServers": {
    "MCPControl": {
      "command": "mcp-control",
      "args": ["--sse"]
    }
  }
}

サーバーの起動

まず、VM またはローカルマシンで MCPControl サーバーを起動します。

mcp-control --sse

サーバーには次の情報が表示されます。

• 利用可能なネットワークインターフェースと IP アドレス
• ポート番号（デフォルト：3232）
• 接続状態のメッセージ

VM のセットアップ例

1. 解像度 1280x720 で Windows VM を起動します
2. VM に MCPControl をインストールします。

   npm install -g mcp-control
   

3. SSE トランスポートで サーバーを実行します。

   mcp-control --sse
   

4. VM の IP アドレス（例：192.168.1.100）を確認します
5. SSE URL を使用して Claude を設定します。

   {
     "mcpServers": {
       "MCPControl": {
         "transport": "sse",
         "url": "http://192.168.1.100:3232/mcp"
       }
     }
   }
   

6. Claude を再起動すると、MCPControl が MCP メニューに表示されます。

🔧 CLI オプション

MCPControl は、高度な設定に使用できる複数のコマンドラインフラグに対応しています。

# Run with SSE transport on default port (3232)
mcp-control --sse

# Run with SSE on custom port
mcp-control --sse --port 3000

# Run with HTTPS/TLS (required for production deployments)
mcp-control --sse --https --cert /path/to/cert.pem --key /path/to/key.pem

# Run with HTTPS on custom port
mcp-control --sse --https --port 8443 --cert /path/to/cert.pem --key /path/to/key.pem

コマンドライン引数

• --sse - ネットワークアクセス用の SSE（Server-Sent Events）トランスポートを有効にします
• --port [number] - カスタムポートを指定します（デフォルト：3232）
• --https - HTTPS/TLS を有効にします（MCP 仕様により、リモート環境へのデプロイで必須）
• --cert [path] - TLS 証明書ファイルのパスです（--https と併用する場合は必須）
• --key [path] - TLS 秘密鍵ファイルのパスです（--https と併用する場合は必須）

セキュリティに関する注意

MCP 仕様によると、本番環境の HTTP ベースのトランスポートでは HTTPS が必須です。MCPControl をリモートアクセス用にデプロイする場合は、必ず有効な TLS 証明書とともに --https フラグを使用してください。

🚀 主な使用例

自動化の支援

• アプリケーションテスト：繰り返し行う UI テストを Claude に任せることで、AI がアプリケーションを操作して問題を報告できるようにします
• ワークフローの自動化：Claude に代わりにアプリケーションを操作させ、繰り返しのタスクを任せることで、創造的な作業に集中できます
• フォーム入力：監督のもとで、データ入力タスクを Claude に任せられます

AI の実験

• AI ゲーム：視覚的なフィードバックを通じて、Claude が簡単なゲームの遊び方を学ぶ様子を観察できます
• 視覚的推論：視覚的なインターフェースを操作して、視覚パズルを解く Claude の能力をテストできます
• 人間と AI の協働：Claude が画面を見て複雑なタスクを支援できる、新しいインタラクションの形を探れます

開発とテスト

• アプリケーション間の連携：通常は通信しないアプリケーションを連携します
• UI テストフレームワーク：ビジュアル検証を用いた堅牢なテストシナリオを作成します
• デモの作成：製品デモの作成を自動化します

⚠️ 重要な免責事項

このソフトウェアは実験的なものであり、危険を伴う可能性があります

このソフトウェアを使用することで、以下の事項を認識し、同意したものとみなされます。

• このツールを通じて AI モデルにコンピューターを直接操作させることには、本質的なリスクが伴います
• このソフトウェアは、マウス、キーボード、その他のシステム機能を操作できるため、意図しない結果を引き起こす可能性があります
• このソフトウェアは、すべてご自身の責任で使用するものとします
• このプロジェクトの作成者およびコントリビューターは、このソフトウェアの使用によって生じる可能性のある損害、データ損失、その他の結果について、一切の責任を負いません
• このツールは、適切な安全対策が講じられた管理環境でのみ使用してください

ご自身の責任でご使用ください

🌟 機能

🪟 ウィンドウ管理 すべてのウィンドウを一覧表示 アクティブウィンドウの情報を取得 フォーカス、サイズ変更、位置変更	🖱️ マウス操作 高精度な移動 クリックとドラッグ操作 スクロールと位置の追跡
⌨️ キーボード操作 テキスト入力とキーの組み合わせ キーの押下／解放を制御 キーを押し続ける機能	📸 画面操作 高品質なスクリーンショット 画面サイズの検出 アクティブウィンドウのキャプチャ

🔧 自動化プロバイダー

MCPControl は、さまざまな用途に対応する複数の自動化プロバイダーをサポートしています。

• keysender（デフォルト）- 高い信頼性を備えた Windows ネイティブの自動化
• powershell - 簡単な操作向けの Windows PowerShell ベースの自動化
• autohotkey - 高度な自動化ニーズに対応する AutoHotkey v2 スクリプト

プロバイダーの設定

環境変数を使用して、自動化プロバイダーを設定できます。

# Use a specific provider for all operations
export AUTOMATION_PROVIDER=autohotkey

# Configure AutoHotkey executable path (if not in PATH)
export AUTOHOTKEY_PATH="C:\Program Files\AutoHotkey\v2\AutoHotkey.exe"

または、特定の操作向けにモジュール式の設定を使用できます。

# Mix and match providers for different operations
export AUTOMATION_KEYBOARD_PROVIDER=autohotkey
export AUTOMATION_MOUSE_PROVIDER=keysender
export AUTOMATION_SCREEN_PROVIDER=keysender  
export AUTOMATION_CLIPBOARD_PROVIDER=powershell

プロバイダー固有のドキュメントを参照してください。

• AutoHotkey プロバイダー

🛠️ 開発環境のセットアップ

コントリビュートやソースからのビルドに関心がある場合は、詳しい手順について CONTRIBUTING.md を参照してください。

開発要件

このプロジェクトを開発用にビルドするには、以下が必要です。

1. Windows オペレーティングシステム（keysender の依存関係に必要）
2. Node.js 18 以降（ビルドツールが含まれる公式 Windows インストーラーを使用してインストールしてください）
3. npm パッケージマネージャー
4. ネイティブビルドツール：
   • node-gyp：npm install -g node-gyp
   • cmake-js：npm install -g cmake-js

keysender の依存関係は、これらのビルドツールを必要とする Windows 固有のネイティブモジュールに依存しています。

📋 プロジェクト構成

• /src
  • /handlers - リクエストハンドラーとツール管理
  • /tools - 中核機能の実装
  • /types - TypeScript 型定義
  • index.ts - アプリケーションのメインエントリーポイント

🔖 リポジトリのブランチ

• main - 最新の機能と変更を含むメイン開発ブランチ
• release - 最新の安定版タグ（現在は v0.2.0）に対応する安定版リリースブランチ

バージョンのインストール

npm を使用して、MCPControl の特定のバージョンをインストールできます。

# Install the latest stable release (from release branch)
npm install mcp-control

# Install a specific version
npm install [email protected]

📚 依存関係

• @modelcontextprotocol/sdk - プロトコル実装用の MCP SDK
• keysender - Windows 専用の UI 自動化ライブラリ
• clipboardy - クリップボードの処理
• sharp - 画像処理
• uuid - UUID の生成

🚧 既知の制限事項

• ウィンドウの最小化／復元操作は現在サポートされていません
• 複数画面に関する機能は、環境によっては期待どおりに動作しない場合があります
• get_screenshot ユーティリティは、VS Code 拡張機能の Cline では動作しません。GitHub の issue #1865を参照してください
• 対象アプリケーションによっては、一部の操作に昇格された権限が必要な場合があります
• Windows のみサポートされています
• MCPControl は、単一画面での 1280x720 解像度で最適に動作します。この解像度に合わせてクリック精度が最適化されています。現在、オフセット／スケーリングのバグに対応しており、テスター、またはテストツールの作成を支援してくださる方を募集しています

👥 貢献

CONTRIBUTING.mdを参照してください

⚖️ ライセンス

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

📖 参考資料

• Model Context Protocol のドキュメント