Maamcp

🚀 MaaMCP

MaaMCPは、MaaFrameworkに基づくMCPサーバーです。AIアシスタントにAndroidデバイスとWindowsデスクトップの自動化機能を提供します。

🚀 クイックスタート

インストール方法

方法1：uvを使ってインストール（推奨）

まずuvをインストールする必要があります。

uvx maa-mcp

方法2：pipを使ってインストール

pip install maa-mcp

方法3：ソースコードからインストール

1. リポジトリをクローンする

   git clone https://github.com/MistEO/MaaMCP.git
   cd MaaMCP
   

2. Pythonの依存関係をインストールする

   pip install -e .
   

クライアントを設定する

Cursorなどのソフトウェアで、MCPサーバーを追加します。

{
  "mcpServers": {
    "MaaMCP": {
      "command": "maa-mcp"
    }
  }
}

または、Cherry Studioなどのソフトウェアで、MCPコマンドを追加します。

uvx maa-mcp

✨ 主な機能

🔍 デバイスの検出と接続

• find_adb_device_list - 利用可能なADBデバイスをスキャンします。
• find_window_list - 利用可能なWindowsウィンドウをスキャンします。
• connect_adb_device - Androidデバイスに接続します。
• connect_window - Windowsウィンドウに接続します。

👀 画面認識

• screencap_and_ocr - 光学文字認識（高速で、優先的に使用することをおすすめします）
• screencap_only - 画面をキャプチャし、その後大規模言語モデルで視覚処理を行います（必要に応じて使用しますが、tokenの消費量が多いです）

🎮 デバイス制御

• click - 指定された座標をクリックします（マルチタッチ/マウスボタンの選択、長押しに対応）
  • Windowsでは、左ボタン、右ボタン、中ボタンなどのマウスボタンを指定できます。
• double_click - 指定された座標をダブルクリックします。
• swipe - スワイプジェスチャー（Androidデバイスのスクロール/ページめくりに優先的に使用）
• input_text - テキストを入力します。
• click_key - キー操作（長押しに対応）
  • Androidでは、戻るキー(4)、ホームキー(3)、メニューキー(82)、音量キーなどのシステムキーをシミュレートできます。
  • Windowsでは、エンター(13)、ESC(27)、方向キーなどの仮想キーコードをサポートします。
• keyboard_shortcut - キーボードショートカット
  • Ctrl+C、Ctrl+V、Alt+Tabなどのコンビネーションキーをサポートします。
• scroll - マウスホイール（Windowsのみ）

📝 Pipelineの生成と実行

• get_pipeline_protocol - Pipelineプロトコルドキュメントを取得します。
• save_pipeline - Pipeline JSONをファイルに保存します（新規作成と更新に対応）
• load_pipeline - 既存のPipelineファイルを読み込みます。
• run_pipeline - Pipelineを実行し、実行結果を返します。
• open_pipeline_in_browser - Pipelineの可視化インターフェースをブラウザで開きます。

💻 使用例

基本的な使用法

設定が完了したら、以下のように使用できます。 Android自動化の例：

MaaMCPツールを使ってAndroidデバイスに接続し、美团を開いて一人前の20元程度の中華料理の注文をしてください。

Windows自動化の例：

MaaMCPツールを使って、現在のPPTのページに回転エフェクトを追加する方法を教えて、操作を見せてください。

Pipeline生成の例：

MaaMCPツールを使ってデバイスに接続し、設定を開き、表示設定に入り、明るさを50%に調整してください。
操作が完了したら、このプロセスのPipeline JSONを生成して、後で直接実行できるようにしてください。

MaaMCPは自動的に以下のことを行います。

1. 利用可能なデバイス/ウィンドウをスキャンします。
2. 接続を確立します。
3. OCRリソースを自動的にダウンロードしてロードします。
4. 認識と操作タスクを実行します。

📚 ドキュメント

大規模言語モデルのプロンプト

AIが自動化タスクを迅速かつ効率的に完了できるようにし、実行過程の詳細な説明を見たくない場合は、以下の内容をプロンプトに追加してください。

# Role: UI Automation Agent

## Workflow Optimization Rules
1. **Minimize Round-Trips**: タスクを最少のインタラクション回数で完了することを目標とします。
2. **Critical Pattern**: フォーム/チャット入力に関する場合は、必ず **[Click Focus -> Input Text -> Send Key]** の原子化操作シーケンスに従ってください。
   - 🚫 誤った方法: まずClickを行い、結果を待ち；次にInputを行い、結果を待ち；最後にEnterを押す。
   - ✅ 正しい方法: `click` の後、返信を待たずに、同じ `tool_calls` リスト内で論理的に `input_text` と `click_key` を追加します。

## Communication Style
- **NO YAPPING**: ユーザーの指示を繰り返さず、手順を説明しないでください。
- **Direct Execution**: 指示を受け取り -> (内部で考える) -> 直接JSONツール呼び出しを出力します。

性能に関する提案

最速の実行速度を得るためには、Flashバージョンの大規模言語モデル（Claude 3 Flashなど）を使用することをおすすめします。これらのモデルは、高いレベルの知能を維持しながら、応答速度を大幅に向上させることができます。

ワークフロー

MaaMCPはシンプルな操作フローに従い、複数のデバイス/ウィンドウでの協調作業をサポートします。

graph LR
    A[デバイスをスキャン] --> B[接続を確立]
    B --> C[自動化操作を実行]

1. スキャン - find_adb_device_list または find_window_list を使用します。
2. 接続 - connect_adb_device または connect_window を使用して（複数のデバイス/ウィンドウに接続でき、複数のコントローラーIDを取得できます）
3. 操作 - 異なるコントローラーIDを指定することで、複数のデバイス/ウィンドウに対してOCR、クリック、スワイプなどの自動化操作を実行します。

Pipeline生成機能

仕組み

graph LR
    A[AIが操作を実行] --> B[操作が完了]
    B --> C[AIがPipelineドキュメントを読む]
    C --> D[AIがPipelineを自動生成]
    D --> E[JSONファイルを保存]
    E --> F[実行検証]
    F --> G{成功したか?}
    G -->|はい| H[完了]
    G -->|いいえ| I[失敗原因を分析]
    I --> J[Pipelineを修正]
    J --> F

1. 操作の実行 - AIがOCR、クリック、スワイプなどの自動化操作を正常に実行します。
2. ドキュメントの取得 - get_pipeline_protocol を呼び出して、Pipelineプロトコルの仕様を取得します。
3. 自動生成 - AIがドキュメントの仕様に基づいて、成功した操作をPipeline JSONに変換します。
4. ファイルの保存 - save_pipeline を呼び出して、生成されたPipelineを保存します。
5. 実行検証 - run_pipeline を呼び出して、Pipelineが正常に実行されるかを確認します。
6. 反復最適化 - 実行結果に基づいて失敗原因を分析し、Pipelineを修正して成功するまで繰り返します。

自動生成の利点

機械的な録画とは異なり、AIによる自動生成には以下の利点があります。

• 成功したパスのみを保存：操作中に複数のパスを試した場合（例えば、最初にAメニューに入って見つからず、戻ってからBメニューに入って見つけた場合）、AIは最終的に成功したパスのみを保存し、失敗した試行を削除します。
• 操作意図の理解：AIは各操作の目的を理解し、意味が明確なノード名を生成します。
• 認識条件の最適化：OCR結果に基づいて、認識領域とマッチング条件を自動的に設定します。
• 検証と反復：実行検証を通じて問題を発見し、自動的に修正してロバスト性を向上させます。

検証と反復最適化

Pipelineが生成された後、AIは自動的に検証と最適化を行います。

1. 実行検証 - Pipelineを実行して、成功したかどうかを確認します。
2. 失敗分析 - 失敗した場合は、具体的にどのノードがエラーになったかとその原因を分析します。
3. 自動修正 - 一般的な最適化手法：
   • 代替認識ノードを追加する（nextリストに複数の候補を追加する）
   • OCRマッチング条件を緩和する（正規表現または部分一致を使用する）
   • roi認識領域を調整する
   • 待機時間を増やす（post_delay）
   • 中間状態検出ノードを追加する
4. 再検証 - 修正後に再度実行し、安定して成功するまで繰り返します。 Pipelineのロジック自体に問題があることが判明した場合、AIは自動化操作を再実行し、新旧の経験を組み合わせてより完璧なPipelineを生成することができます。

サンプル出力

{
  "開始任务": {
    "recognition": "DirectHit",
    "action": "DoNothing",
    "next": ["点击设置"]
  },
  "点击设置": {
    "recognition": "OCR",
    "expected": "设置",
    "action": "Click",
    "next": ["进入显示"]
  },
  "进入显示": {
    "recognition": "OCR",
    "expected": "显示",
    "action": "Click",
    "next": ["调整亮度"]
  },
  "调整亮度": {
    "recognition": "OCR",
    "expected": "亮度",
    "action": "Swipe",
    "begin": [200, 500],
    "end": [400, 500],
    "duration": 200
  }
}

注意事項

⚠️ 重要提示

• Windows自動化の制限：

• 一部のゲームやアプリケーションの不正防止機能が、バックグラウンド制御操作をブロックする可能性があります。
• ターゲットアプリケーションが管理者権限で実行されている場合は、MaaMCPも管理者権限で起動する必要があります。
• 最小化されたウィンドウに対する操作はサポートされていません。ターゲットウィンドウを最小化しない状態に保ってください。
• デフォルトのバックグラウンドスクリーンショット/入力方法が使用できない場合（スクリーンショットが空、操作が応答しないなど）、AIアシスタントはフロントエンド方式に切り替える可能性があり、その際はマウスとキーボードが占有されます。

よくある質問

OCR認識が失敗し、「Failed to load det or rec」というエラーが表示されるか、リソースが存在しないという警告が表示される場合

初回使用時に、OCRモデルファイルが自動的にダウンロードされますが、ダウンロードが失敗することがあります。以下のデータディレクトリを確認してください。

• Windows: C:\Users\<ユーザー名>\AppData\Local\MaaXYZ\MaaMCP\resource\model\ocr\
• macOS: ~/Library/Application Support/MaaXYZ/MaaMCP/resource/model/ocr/
• Linux: ~/.local/share/MaaXYZ/MaaMCP/resource/model/ocr/

1. 上記のディレクトリにモデルファイル（det.onnx, rec.onnx, keys.txt）があるかどうかを確認してください。
2. model/download.log でリソースダウンロードの異常が発生していないかを確認してください。
3. python -c "from maa_mcp.download import download_and_extract_ocr; download_and_extract_ocr()" を手動で実行して、再度ダウンロードを試みてください。

ISSUEについて

問題を報告する際は、ログファイルを提供してください。ログファイルのパスは以下の通りです。

• Windows: C:\Users\<ユーザー名>\AppData\Local\MaaXYZ\MaaMCP\debug\maa.log
• macOS: ~/Library/Application Support/MaaXYZ/MaaMCP/debug/maa.log
• Linux: ~/.local/share/MaaXYZ/MaaMCP/debug/maa.log

📄 ライセンス

このプロジェクトは GNU AGPL v3 ライセンスの下で公開されています。

謝辞

• MaaFramework - 強力な自動化フレームワークを提供してくれました。
• FastMCP - MCPサーバーの開発を簡素化してくれました。
• Model Context Protocol - AIツールの統合標準を定義してくれました。