scrcpy-mcp

Name: scrcpy-mcp
Author: JuanCF

ローカル

github.com/JuanCF開発ツール1255 週間前に更新

リポジトリ

scrcpy-mcp について

scrcpy-mcp は、ADB と scrcpy を通じて AI エージェントに Android デバイスの画面認識と操作を提供する MCP サーバーです。スマートフォンの操作を自動化したい開発者を想定しており、セッション有効時は scrcpy の高速経路を使い、ADB を代替手段とします。

主な機能

01画面キャプチャ・入力・アプリ管理の 44 ツール
02scrcpy 制御プロトコルによる高速な入力とキャプチャ
03スクリーンショットを画像として AI に返却
04オーディオのストリーミングと録音に対応
05ui_find_element によるタップ座標の取得

活用シーン

01AI エージェントによる Android アプリの UI テスト自動化
02実機画面のリモート表示と操作
03デバイスとのファイル転送やシェルコマンド実行

MCP 対応

本プロジェクトは MCP サーバーとして、Claude Code、Cursor、VS Code などの MCP クライアントに、デバイス制御・スクリーンショット・UI 自動化ツールを公開します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "juancf-scrcpy": {
      "command": "npx",
      "args": [
        "-y",
        "scrcpy-mcp"
      ],
      "env": {
        "ANDROID_SERIAL": "<ANDROID_SERIAL>",
        "ADB_PATH": "<ADB_PATH>",
        "SCRCPY_SERVER_PATH": "<SCRCPY_SERVER_PATH>"
      }
    }
  }
}

起動コマンドnpx -y scrcpy-mcp

設定が必要な環境変数

ANDROID_SERIALTarget device serial number (from `adb devices`). Required when multiple devices are connected.

ADB_PATHCustom path to the adb binary. Defaults to 'adb' on PATH.

SCRCPY_SERVER_PATHPath to the scrcpy-server.jar file. Only needed if not installed in a standard location.

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npmscrcpy-mcp0.5.0stdio

ツール

掲載時のツール一覧 · 2 週間前に更新

パラメーター	型	必須	説明
maxFps	integer	いいえ	最大フレームレート（デフォルト：30）
serial	string	いいえ	デバイスのシリアル番号
maxSize	integer	いいえ	画面の最大寸法（ピクセル、デフォルト：1024）

詳細

scrcpy-mcp

ADB と scrcpy を介して Android デバイスを完全に認識し、操作できるようにする MCP サーバーです。

MCP 互換の AI アシスタント（Claude Code、OpenCode、Cursor、VS Code Copilot など）を Android デバイスに接続できます。AI は画面を確認し、タップ、スワイプ、入力、アプリの起動、UI 要素の検査、ファイルの転送、シェルコマンドの実行ができます。

特長

44 個のツールで、スクリーンショット、入力、アプリ、UI の自動化、シェル、ファイル、クリップボード、動画ストリーミング、音声のストリーミング／録音に対応します
scrcpy を優先：scrcpy のバイナリ制御プロトコルを使用して、入力を 10～50 倍高速化し、ほぼ瞬時のスクリーンショット（約 33 ms）を実現します
ADB フォールバック：scrcpy がなくても操作ツールを利用できます。速度は低下しますが、いつでも使用できます（音声ツール start_audio_stream／audio_record_start と動画ストリームには scrcpy が必要です）
画像を返すスクリーンショット：AI はファイルパスだけでなく、実際に画面を確認できます
UI 要素の検索：ui_find_element はタップ座標を返すため、AI は画面で確認した内容に基づいて操作できます
音声のストリーミングと録音：デバイスの音声をホストのスピーカーにストリーミングする（start_audio_stream）、または .wav／.opus にキャプチャする（audio_record_start）ことができます
Android 10 以降で使えるクリップボード：ADB のみを使う方法で生じる制限を scrcpy が回避します

前提条件

必須

要件	インストール	確認
Node.js 24 以降	nodejs.org または `nvm install`（`.nvmrc` を使用）	`node --version`
ADB（Android Platform Tools）	developer.android.com/tools/releases/platform-tools	`adb version`
USB デバッグが有効な Android デバイス（音声を使用するには Android 11 以降）	設定 → 開発者向けオプション → USB デバッグ	`adb devices`

任意（パフォーマンス向上）

要件	インストール	メリット
scrcpy	github.com/Genymobile/scrcpy	入力が 10～50 倍高速化し、スクリーンショットは約 33 ms
ffmpeg	`apt install ffmpeg` / `brew install ffmpeg`	scrcpy 動画ストリームのデコード、音声録音、音声クリップのキャプチャに必要です
ffplay	通常は ffmpeg に同梱されています	音声再生と MJPEG ビューアーウィンドウに必要です

デバイスのセットアップ

開発者向けオプションを有効にします：設定 → デバイス情報 →「ビルド番号」を 7 回タップ
USB デバッグを有効にします：設定 → 開発者向けオプション → USB デバッグ
USB でデバイスを接続します
デバイスに表示される RSA フィンガープリントの確認を承認します
確認します：adb devices にデバイスが device として表示される必要があります（unauthorized ではありません）

インストール

# Run directly with npx (no install needed)
npx scrcpy-mcp

# Or install globally
npm install -g scrcpy-mcp

MCP クライアントの設定

Claude Code

claude mcp add android -- npx scrcpy-mcp

または、プロジェクトのルートにある .mcp.json に追加します：

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"]
    }
  }
}

OpenCode

.mcp.json に追加します：

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"]
    }
  }
}

Cursor

設定 → MCP → サーバーを追加：

{
  "android": {
    "command": "npx",
    "args": ["scrcpy-mcp"]
  }
}

Claude Desktop

~/.config/Claude/claude_desktop_config.json（Linux）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します：

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"]
    }
  }
}

VS Code（GitHub Copilot）

.vscode/mcp.json に追加します：

{
  "servers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"]
    }
  }
}

環境変数のカスタマイズ

標準とは異なる scrcpy-server のパスを指定するなど、カスタムオプションを設定する必要がある場合は、サーバー設定に "env" オブジェクトを追加できます。例：

{
  "mcpServers": {
    "android": {
      "command": "npx",
      "args": ["scrcpy-mcp"],
      "env": {
        "SCRCPY_SERVER_PATH": "C:\\path\\to\\scrcpy-server"
      }
    }
  }
}

注：SCRCPY_SERVER_VERSION を設定するのは、バージョンの自動検出に失敗した場合に限ってください。この設定は検出結果を上書きするため、古い値を指定すると、トラブルシューティングで説明されているバージョン不一致が発生します。インストール済みの scrcpy のバージョンに合わせてください（scrcpy --version）。

注：Windows では、設定パス内のバックスラッシュを二重にエスケープ（\\）してください。

OpenCode ユーザー向け： OpenCode では、MCP サーバーに環境変数を渡す際に "env" ではなく "environment" を使用します。opencode.json で scrcpy-mcp を設定する場合は、上記の例の "env" を "environment" に置き換えてください。

ツールのリファレンス

セッション管理

ツール	説明
`start_session`	scrcpy セッションを開始します。有効な場合、入力とスクリーンショットには高速パス（10～50 倍高速）が使用されます。
`stop_session`	scrcpy セッションを停止します。ツールは ADB にフォールバックします。
`version`	セッションでプッシュされる scrcpy-server のバージョンと、そのバージョンの解決元を報告します。

start_session のオプション：

オプション	デフォルト	説明
`maxSize`	`1024`	動画フレームの最大寸法（ピクセル）
`maxFps`	`30`	1 秒あたりの最大フレーム数
`audio`	`false`	音声をキャプチャします（以下の注意事項を参照）
`audioSource`	`output`	音声ソース（`output`、`playback`、`mic`、`voice-call`、…）
`audioDup`	`false`	`audioSource: "playback"` の場合、デバイスでの再生音を聞こえる状態に保ちます（Android 13 以降）
`stayAwake`	`false`	セッション全体を通してデバイスの電源をオンの状態に保ちます（scrcpy `--stay-awake`）。デバイスが充電器に接続されている間のみ適用されます。
`screenOffTimeout`	（デバイスの設定）	セッション全体に適用する画面消灯までのタイムアウト（秒）（scrcpy `--screen-off-timeout`）。バッテリー駆動時も動作します。scrcpy 2.5 以降が必要です。

画面の点灯状態に関するどちらのオプションも一時的なものです。scrcpy は、セッション終了時にデバイスの元の値に戻します。音声をオンにするためにツールがセッションを再起動した場合も同様です。

動画ストリーミング

ツール	説明
`start_video_stream`	HTTP MJPEG 動画ストリームを開始し、ビューアウィンドウ（ffplay）を開きます。必要に応じて scrcpy セッションを自動的に開始します。
`stop_video_stream`	動画ストリームを停止し、ビューアウィンドウを閉じます。

音声ストリーミングと録音

注意： 音声キャプチャはオプトインで、Android 11 以降が必要です。デフォルトのソース output は REMOTE_SUBMIX を使用するため、キャプチャ中はデバイス本体のスピーカーがミュートされます。音声はコピーされるのではなく、ホストに移動されます。デバイスから音を出し続けるには、audioSource: "playback" と audioDup: true（Android 13 以降）を使用してください。録音はホストのファイルシステムに保存されます。

ツール	説明
`start_audio_stream`	デバイスの音声を ffplay 経由でホストのスピーカーにストリーミングします。音声なしで開始された scrcpy セッションは再起動されます。
`stop_audio_stream`	ホストへの音声ストリーミングを停止します。
`audio_record_start`	ホスト上でデバイス音声の録音を `.wav`（デフォルト）または `.opus` で開始します。必要に応じて scrcpy セッションを再起動します。`maxDuration` 秒後（デフォルトは 300 秒）に自動的に停止します。
`audio_record_stop`	録音を停止し、ホスト側のファイルを確定します。
`audio_capture`	指定した長さのデバイス音声をキャプチャし、音声コンテンツブロックとして返します。必要に応じて scrcpy セッションを再起動します。`durationSeconds` のデフォルトは 5 です（整数、最大 30。ffmpeg に libopus がなく WAV フォールバックが使用される場合、デフォルトの 5 秒は 2.5 秒になります）。`audioSource`／`audioDup` は実行中の音声セッションの設定がデフォルトとなるため、録音やストリームを中断せずにクリップを取得できます。

デバイス管理

ツール	説明
`device_list`	接続されているすべてのデバイスについて、シリアル番号、状態、モデルを一覧表示します
`device_info`	モデル、Android のバージョン、画面サイズ、SDK レベル、バッテリー情報を取得します
`screen_on`	デバイスの画面を点灯します
`screen_off`	画面を消灯します
`rotate_device`	画面を回転します（アクティブなセッションが必要です）
`expand_notifications`	通知パネルをプルダウンします（アクティブなセッションが必要です）
`expand_settings`	クイック設定パネルをプルダウンします（アクティブなセッションが必要です）
`collapse_panels`	通知パネル／設定パネルを閉じます（アクティブなセッションが必要です）
`connect_wifi`	WiFi ADB を有効にし、デバイスにワイヤレス接続します。接続アドレスを返します。
`disconnect_wifi`	ワイヤレス接続された ADB デバイスとの接続を切断します

画面表示

ツール	説明
`screenshot`	画面をキャプチャし、画像として返します。scrcpy では約 33ms、ADB 経由では約 500ms です。
`screen_record_start`	デバイス上のファイルへの画面録画を開始します
`screen_record_stop`	録画を停止し、必要に応じてファイルをホストに転送します

入力操作

入力ツールは、セッションがアクティブな場合はすべて scrcpy（約 5～10ms）を使用し、それ以外の場合は ADB（約 100～300ms）にフォールバックします。

ツール	説明
`tap`	画面上の座標をタップします
`swipe`	ある点から別の点へスワイプします
`long_press`	指定した座標を長押しします
`drag_drop`	ある点から別の点へドラッグします
`input_text`	フォーカスされているフィールドにテキストを入力します
`key_event`	キーイベントを送信します：HOME、BACK、ENTER、VOLUME_UP、VOLUME_DOWN、POWER など
`scroll`	指定した位置でスクロールします（dx＝水平、dy＝垂直）

アプリ管理

ツール	説明
`app_start`	パッケージ名を指定してアプリを起動します。先頭に `+` を付けると、起動前に強制終了します。
`app_stop`	アプリを強制終了します
`app_install`	ホストマシンから APK をインストールします
`app_uninstall`	アプリをアンインストールします
`app_list`	インストール済みパッケージを一覧表示します。名前またはシステム／サードパーティで絞り込むこともできます
`app_current`	現在のフォアグラウンドアプリとアクティビティを取得します

UI 自動化

ツール	説明
`ui_dump`	UI 階層全体を XML としてダンプします
`ui_find_element`	テキスト、リソース ID、クラス名、またはコンテンツ説明から要素を検索します。タップ座標を返します。

シェルとファイル

ツール	説明
`shell_exec`	任意の ADB シェルコマンドを実行し、出力を返します
`file_push`	ホストマシンからデバイスにファイルを転送します
`file_pull`	デバイスからホストマシンにファイルを転送します
`file_list`	デバイス上のディレクトリの内容を一覧表示します

クリップボード

ツール	説明
`clipboard_get`	クリップボードの内容を取得します。scrcpy を使用して Android 10 以降の制限を回避します。
`clipboard_set`	クリップボードの内容を設定します。`paste: true` を渡すと、すぐに貼り付けも行います。

パフォーマンス

操作	scrcpy（セッションがアクティブ）	ADB フォールバック
スクリーンショット	約 33ms	約 500ms
タップ／スワイプ	約 5～10ms	約 100～300ms
テキスト入力	約 5ms	約 100～300ms
クリップボード	約 10ms	Android 10 以降では信頼性なし

高速処理を有効にするには、最初に一度セッションを開始します：

start_session → take screenshots → tap → swipe → ...

環境変数

変数	デフォルト	説明
`ADB_PATH`	`adb`	ADB バイナリへのパス
`ANDROID_SERIAL`	（なし）	デフォルトのデバイスシリアル。自動検出より優先されます
`SCRCPY_SERVER_PATH`	（自動）	scrcpy-server バイナリへのパス
`SCRCPY_SERVER_VERSION`	（自動）	scrcpy-server バイナリのバージョン
`FFMPEG_PATH`	`ffmpeg`	ffmpeg バイナリへのパス
`FFPLAY_PATH`	`ffplay`	ffplay バイナリへのパス（動画ストリームビューアーおよび音声再生）

デバイスが 1 台だけ接続されている場合、ツールは自動検出します。複数のデバイスが接続されている場合は、serial パラメーターを明示的に渡すか、ANDROID_SERIAL を設定してください。

トラブルシューティング

adb devices に unauthorized と表示される デバイスに表示される RSA フィンガープリントの確認プロンプトを承認してください。プロンプトが表示されない場合は、開発者向けオプションで USB デバッグの承認を取り消してから再接続してください。 start_session が失敗する scrcpy がインストールされており、scrcpy-server バイナリにアクセスできることを確認してください。Windows では、scrcpy.exe と scrcpy-server の両方が含まれるフォルダーを PATH に追加するか、SCRCPY_SERVER_PATH に scrcpy-server ファイルのフルパスを設定してください。

ファイルとディレクトリ：SCRCPY_SERVER_PATH が、親フォルダーではなく、scrcpy-server ファイル自体を直接指していることを確認してください（例：C:\path\to\scrcpy-server）。
Android のディレクトリ競合：以前にサーバーパスへディレクトリをプッシュした場合、Android デバイス上の /data/local/tmp/scrcpy-server.jar がフォルダーとして作成されている可能性があります。adb shell rm -rf /data/local/tmp/scrcpy-server.jar を実行して削除してください。
バージョンの不一致：クライアントは、プッシュする scrcpy-server ファイルと完全に一致するバージョンを送信する必要があります。これを保証するため、サーバーとバージョンが別々に解決されることはありません。scrcpy のインストール先がペアとして解決され、バージョンは同じインストール先に属するクライアントから取得されます。インストール先は次の順序で見つかります。SCRCPY_SERVER_PATH が設定されている場合はそこから（クライアントはサーバーと同じ場所、または ../../bin/scrcpy の位置にあるプレフィックスから検索されます）。設定されていない場合は、PATH 上の scrcpy から検索され、サーバーはその隣、または ../share/scrcpy/scrcpy-server にあるものとして検索されます。それ以外の場合は、パッケージマネージャー（dpkg、pacman、rpm、apk、brew）が報告する場所が使用されます。シンボリックリンクされたクライアントは、対応するファイルの場所を特定する前に実際のディレクトリへ解決されるため、Homebrew の bin/scrcpy のようなリンクファームは、リンク自体のディレクトリではなく、リンク先のインストール先とペアになります。SCRCPY_SERVER_VERSION が設定されている場合は、検出されたバージョンを上書きします。そのため、Windows の場合や、GUI アプリがシェルの PATH を使わずに MCP を起動する場合は、SCRCPY_SERVER_PATH を完全な scrcpy インストール先内のサーバーに設定するだけで十分です。また、PATH 上で別の scrcpy が先に見つかっても、こちらが優先されます。ただし、バージョンの読み取り時にそのインストール先の実行ファイルが実行されるため、SCRCPY_SERVER_PATH は信頼できるインストール先にのみ設定してください（サーバーファイル自体もデバイスにプッシュされて実行されるため、同じ信頼性が必要です）。解決されたサーバーに対応するクライアントが見つからない場合（たとえば、リリースページからダウンロードした scrcpy-server のみの場合）、クライアントはデフォルトのバージョンにフォールバックし、サーバーがバージョン不一致エラーで終了する可能性があります。SCRCPY_SERVER_VERSION にインストール済みのバージョン（例："4.1"）を設定してください。使用中のバージョンと、その解決元を確認するには、version ツールを実行してください。上記の環境変数の表を参照してください。

スクリーンショットの取得が遅い（約500ms） 高速な動画ストリーム経路を有効にするには、start_session で scrcpy セッションを開始してください。scrcpy と ffmpeg が必要です。

expand_notifications / expand_settings / collapse_panels が失敗する これらのツールにはアクティブな scrcpy セッションが必要です。先に start_session を実行してください。

長時間の自動操作中にデバイスの画面がオフになり続ける セッションを stayAwake: true（充電中のみ）または screenOffTimeout: <seconds> を指定して開始してください。後者はバッテリー駆動中も機能します。どちらもセッション終了時に元の状態に戻ります。

start_audio_stream で ffplay が見つからないと表示される ffmpeg をインストールしてください（ffplay は ffmpeg に含まれています）。または、FFPLAY_PATH にバイナリのパスを設定してください。audio_record_start と FFMPEG_PATH にも同じことが当てはまります。

録音した音声が無音になる REMOTE_SUBMIX がキャプチャするのは、アプリが実際に再生している音声のみです。何も再生されていないときに録音すると、デジタル無音になりますが、これは想定どおりです。また、デバイスがミュートされていないことを確認してください。デフォルトの output ソースでは音声がホストに移動するため、キャプチャ中はデバイスから音が出なくなることにも注意してください。音声を聞こえる状態に保つには、audioSource: "playback" と audioDup: true を使用してください（Android 13 以降）。

音声ツールで音声が利用できないと報告される 音声のキャプチャには Android 11 以降（SDK 30）が必要です。古いデバイスでも、セッションを動画、入力、クリップボードに使用できます。

Android 10 以降でクリップボードが機能しない Android 10 以降では ADB によるクリップボードへのアクセスが制限されています。scrcpy セッションを開始してください。scrcpy のクリップボードプロトコルを使うと、この制限を回避できます。 複数のデバイスが接続されている場合 各ツールに serial を渡すか、ANDROID_SERIAL 環境変数を設定してください。

セキュリティ

このサーバーは、接続されている Android デバイスを完全に制御できます。shell_exec ツールは任意のコマンドを実行でき、file_push／file_pull はシェルユーザーがアクセスできる任意のファイルを読み書きできます。

サーバーは stdio 経由でローカルに実行され、ネットワークには公開されません
ADB を使用するには、デバイスで USB デバッグを明示的に有効にする必要があります
初回接続時に、デバイスがホストの RSA キーを承認する必要があります
自分が所有するデバイスのみを接続し、使用する AI エージェントが信頼できることを確認してください

ライセンス

MIT — LICENSE をご覧ください

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

scrcpy-mcp

scrcpy-mcp について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

scrcpy-mcp

特長

前提条件

必須

任意（パフォーマンス向上）

デバイスのセットアップ

インストール

MCP クライアントの設定

Claude Code

OpenCode

Cursor

Claude Desktop

VS Code（GitHub Copilot）

環境変数のカスタマイズ

ツールのリファレンス

セッション管理

動画ストリーミング

音声ストリーミングと録音

デバイス管理

画面表示

入力操作

アプリ管理

UI 自動化

シェルとファイル

クリップボード

パフォーマンス

環境変数

トラブルシューティング

セキュリティ

ライセンス

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？