📱 Phone MCP Plugin

📱 Phone MCP Plugin

🌟 ADB コマンドを使って、Android スマートフォンを簡単に操作できる強力な MCP プラグインです。

例

• 今日の天気をブラウザーで調べ、その内容に基づいて自動でNetease Musicを選択して再生します。確認は不要です。

• 連絡先からHaoに電話をかけます。応答がない場合は、会議室101に来るようSMSを送信します。

中国語ドキュメント

⚡ クイックスタート

📥 インストール

Python 3.10+ と uv を使って、隔離された環境で実行します。

uvx --with "mcp<2" --with requests phone-mcp

追加の依存関係は、既存のPyPIリリースとのMCP v1 API互換性を維持し、マップモジュールがインポートする requests を提供します。これらは更新済みのソースパッケージで宣言されていますが、旧リリースでは必要です。

uvを使って永続的にインストールする場合：

uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python phone-mcp "mcp<2" requests
.venv/bin/phone-cli --help

または、Linux/macOSでPython組み込みの仮想環境とpipを使います。

python3 -m venv .venv
.venv/bin/python -m pip install phone-mcp "mcp<2" requests
.venv/bin/phone-cli --help

Windowsでは、py -3 -m venv .venv で環境を作成し、上記の .venv/bin/ のパスの代わりに .venv\Scripts\python.exe と .venv\Scripts\phone-cli.exe を使用してください。

Debian/Ubuntuで externally-managed-environment エラーが発生する場合、システムPythonはOSによって管理されています。uvx または仮想環境を使用してください。sudo pip や --break-system-packages で回避しないでください。venv が利用できない場合は、まずシステムのパッケージマネージャーで python3-venv をインストールしてください。

🔧 設定

AI アシスタントの設定

AI アシスタントの設定（Cursor、Trae、Claudeなど）で構成します。

{
    "mcpServers": {
        "phone-mcp": {
            "command": "uvx",
            "args": [
                "--with", "mcp<2",
                "--with", "requests",
                "phone-mcp"
            ]
        }
    }
}

または、pipでインストールした場合：

{
    "mcpServers": {
        "phone-mcp": {
            "command": "/absolute/path/to/.venv/bin/python",
            "args": [
                "-m",
                "phone_mcp"
            ]
        }
    }
}

重要：phone-mcpをインストールした仮想環境内のPythonの絶対パスを使用してください。システムPythonは使用しないでください。Linux/macOSでは /absolute/path/to/.venv/bin/python、Windowsでは C:\path\to\.venv\Scripts\python.exe を使用します（JSONではバックスラッシュを \\ にエスケープしてください）。AI アシスタントを起動する前に環境を有効化する必要はありません。

注：Cursorでは、この設定を ~/.cursor/mcp.json に記述してください。

使い方：

• たとえば、Claudeとの会話でコマンドを直接使用します。

  Please call contact hao
  

⚠️ 使用する前に、次の点を確認してください。

• ADBが正しくインストールおよび設定されていること
• AndroidデバイスでUSBデバッグが有効になっていること
• デバイスがUSB経由でコンピューターに接続されていること

🎯 主な機能

• 📞 通話機能：発信、通話終了、着信の受信
• 💬 メッセージ：SMSの送受信、メッセージの生データ取得
• 👥 連絡先：スマートフォンの連絡先へのアクセス、自動UI操作による新しい連絡先の作成
• 📸 メディア：スクリーンショット、画面録画、メディア操作
• 📱 アプリ：アプリの起動、インテントによる特定アクティビティの起動、インストール済みアプリの一覧表示、アプリの終了
• 🔧 システム：ウィンドウ情報、アプリのショートカット
• 🗺️ マップ：電話番号付きのPOIを検索
• 🖱️ UI操作：タップ、スワイプ、テキスト入力、キー押下
• 🔍 UI検査：テキスト、ID、クラス、説明による要素の検索
• 🤖 UI自動化：要素が表示されるまで待機、要素を見つけるためのスクロール
• 🧠 画面分析：構造化された画面情報と統一された操作
• 🌐 ウェブブラウザー：デバイスの既定のブラウザーでURLを開く
• 🔄 UI監視：UIの変化を監視し、特定の要素が表示または非表示になるまで待機

🛠️ 要件

• Python 3.10+
• USBデバッグが有効なAndroidデバイス
• ADBツール

📋 基本コマンド

デバイスと接続

# Check device connection
phone-cli check

# Get screen size
phone-cli screen-interact find method=clickable

通信

# Make a call
phone-cli call 1234567890

# End current call
phone-cli hangup

# Send SMS
phone-cli send-sms 1234567890 "Hello"

# Get received messages (with pagination)
phone-cli messages --limit 10

# Get sent messages (with pagination)
phone-cli sent-messages --limit 10

# Get contacts (with pagination)
phone-cli contacts --limit 20

# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"

メディアとアプリ

# Take screenshot
phone-cli screenshot

# Record screen
phone-cli record --duration 30

# Launch app (may not work on all devices)
phone-cli app camera

# Alternative app launch method using open_app (if app command doesn't work)
phone-cli open_app camera

# Close app
phone-cli close-app com.android.camera

# List installed apps (basic info, faster)
phone-cli list-apps

# List apps with pagination
phone-cli list-apps --page 1 --page-size 10

# List apps with detailed info (slower)
phone-cli list-apps --detailed

# Launch specific activity (reliable method for all devices)
phone-cli launch com.android.settings/.Settings

# Launch app by package name (may not work on all devices)
phone-cli app com.android.contacts

# Alternative launch by package name (if app command doesn't work)
phone-cli open_app com.android.contacts

# Launch app by package and activity (most reliable method)
phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity

# Open URL in default browser
phone-cli open-url google.com

画面分析と操作

# Analyze current screen with structured information
phone-cli analyze-screen

# Unified interaction interface
phone-cli screen-interact <action> [parameters]

# Tap at coordinates
phone-cli screen-interact tap x=500 y=800

# Tap element by text
phone-cli screen-interact tap element_text="Login"

# Tap element by content description
phone-cli screen-interact tap element_content_desc="Calendar"

# Swipe gesture (scroll down)
phone-cli screen-interact swipe x1=500 y1=1000 x2=500 y2=200 duration=300

# Press key
phone-cli screen-interact key keycode=back

# Input text
phone-cli screen-interact text content="Hello World"

# Find elements
phone-cli screen-interact find method=text value="Login" partial=true

# Wait for element
phone-cli screen-interact wait method=text value="Success" timeout=10

# Scroll to find element
phone-cli screen-interact scroll method=text value="Settings" direction=down max_swipes=5

# Monitor UI for changes
phone-cli monitor-ui --interval 0.5 --duration 30

# Monitor UI until specific text appears
phone-cli monitor-ui --watch-for text_appears --text "Welcome"

# Monitor UI until specific element ID appears
phone-cli monitor-ui --watch-for id_appears --id "login_button"

# Monitor UI until specific element class appears
phone-cli monitor-ui --watch-for class_appears --class-name "android.widget.Button"

# Monitor UI changes with output as raw JSON
phone-cli monitor-ui --raw

位置情報とマップ

# Search nearby POIs with phone numbers
phone-cli get-poi 116.480053,39.987005 --keywords restaurant --radius 1000

📚 高度な使い方

アプリとアクティビティの起動

プラグインでは、複数の方法でアプリやアクティビティを起動できます。

1. アプリ名で指定（2 つの方法）：

   # Method 1: Using app command (may not work on all devices)
   phone-cli app camera
   
   # Method 2: Using open_app command (alternative if app command fails)
   phone-cli open_app camera
   

2. パッケージ名で指定（2 つの方法）：

   # Method 1: Using app command (may not work on all devices)
   phone-cli app com.android.contacts
   
   # Method 2: Using open_app command (alternative if app command fails)
   phone-cli open_app com.android.contacts
   

3. パッケージ名とアクティビティで指定（最も信頼性の高い方法）：

   # This method works on all devices
   phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity
   

注意：app または open_app コマンドで問題が発生した場合は、最も確実に実行できるよう、常に完全なコンポーネント名（パッケージ名／アクティビティ）を指定して launch コマンドを使用してください。

UI オートメーションによる連絡先の作成

プラグインでは、UI 操作を通じて連絡先を作成できます。

# Create a new contact with UI automation
phone-cli create-contact "John Doe" "1234567890"

このコマンドは次の操作を行います。

1. 連絡先アプリを開きます
2. 連絡先の作成画面に移動します
3. 名前と電話番号の欄に入力します
4. 連絡先を自動的に保存します

画面ベースのオートメーション

統合された画面操作インターフェースにより、エージェントは次の操作を簡単に行えます。

1. 画面の分析：UI 要素とテキストの構造化された分析結果を取得します
2. 判断：検出された UI パターンと利用可能なアクションに基づいて判断します
3. 操作の実行：一貫したパラメーターシステムを通じて操作します

UI の監視とオートメーション

プラグインには、インターフェースの変化を検出する強力な UI 監視機能が備わっています。

1. 基本的な UI 監視：

   # Monitor any UI changes with custom interval (seconds)
   phone-cli monitor-ui --interval 0.5 --duration 30
   

2. 特定の要素が表示されるまで待機：

   # Wait for text to appear (useful for automated testing)
   phone-cli monitor-ui --watch-for text_appears --text "Login successful"
   
   # Wait for specific ID to appear
   phone-cli monitor-ui --watch-for id_appears --id "confirmation_dialog"
   

3. 要素が消えるまで監視：

   # Wait for text to disappear
   phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
   

4. UI の変更に関する詳細なレポートを取得：

   # Get raw JSON data with all UI change information
   phone-cli monitor-ui --raw
   

ヒント：UI 監視は、読み込み画面が完了するまで待機したり、UI 上で操作が反映されたことを確認したりするオートメーションスクリプトで特に役立ちます。

📚 詳細なドキュメント

ドキュメントと設定の詳細については、GitHub リポジトリをご覧ください。

🧰 ツールのドキュメント

画面インターフェース API

プラグインには、デバイスを操作するための包括的な API を備えた強力な画面インターフェースが用意されています。主な関数とそのパラメーターを以下に示します。

interact_with_screen

async def interact_with_screen(action: str, params: Dict[str, Any] = None) -> str:
    """Execute screen interaction actions"""

• パラメーター：
  • action：アクションの種類（"tap"、"swipe"、"key"、"text"、"find"、"wait"、"scroll"）
  • params：各アクションの種類に固有のパラメーターを含む辞書
• 戻り値： 操作結果を含む JSON 文字列

例：

# Tap by coordinates
result = await interact_with_screen("tap", {"x": 100, "y": 200})

# Tap by element text
result = await interact_with_screen("tap", {"element_text": "Login"})

# Swipe down
result = await interact_with_screen("swipe", {"x1": 500, "y1": 300, "x2": 500, "y2": 1200, "duration": 300})

# Input text
result = await interact_with_screen("text", {"content": "Hello world"})

# Press back key
result = await interact_with_screen("key", {"keycode": "back"})

# Find element by text
result = await interact_with_screen("find", {"method": "text", "value": "Settings", "partial": True})

# Wait for element to appear
result = await interact_with_screen("wait", {"method": "text", "value": "Success", "timeout": 10, "interval": 0.5})

# Scroll to find element
result = await interact_with_screen("scroll", {"method": "text", "value": "Privacy Policy", "direction": "down", "max_swipes": 8})

analyze_screen

async def analyze_screen(include_screenshot: bool = False, max_elements: int = 50) -> str:
    """Analyze the current screen and provide structured information about UI elements"""

• パラメーター：
  • include_screenshot：結果に Base64 エンコードされたスクリーンショットを含めるかどうか
  • max_elements：処理する UI 要素の最大数
• 戻り値： 詳細な画面分析結果を含む JSON 文字列

create_contact

async def create_contact(name: str, phone: str) -> str:
    """Create a new contact with the given name and phone number"""

• パラメーター：
  • name：連絡先の氏名
  • phone：連絡先の電話番号
• 戻り値： 操作結果を含む JSON 文字列
• 場所： この関数は「contacts.py」モジュールにあり、UI オートメーションを実行して連絡先を作成します

launch_app_activity

async def launch_app_activity(package_name: str, activity_name: Optional[str] = None) -> str:
    """Launch an app using package name and optionally an activity name"""

• パラメーター：
  • package_name：起動するアプリのパッケージ名
  • activity_name：起動する特定のアクティビティ（任意）
• 戻り値： 操作結果を含む JSON 文字列
• 場所： この関数は「apps.py」モジュールにあります

launch_intent

async def launch_intent(intent_action: str, intent_type: Optional[str] = None, extras: Optional[Dict[str, str]] = None) -> str:
    """Launch an activity using Android intent system"""

• パラメーター：
  • intent_action：実行するアクション
  • intent_type：インテントの MIME タイプ（任意）
  • extras：インテントとともに渡す追加データ（任意）
• 戻り値： 操作結果を含む JSON 文字列
• 場所： この関数は「apps.py」モジュールにあります

📄 ライセンス

Apache License, Version 2.0

連絡先作成ツール

このツールは、ADB を使用して Android デバイス上に連絡先を簡単に作成できます。

前提条件

• Python 3.x
• ADB（Android Debug Bridge）がインストールされ、設定されていること
• Android デバイスが接続され、ADB での操作が許可されていること

使用方法

基本的な使い方

スクリプトを実行するだけです。

python create_contact.py

これにより、次のデフォルト値を使用して連絡先が作成されます。

• アカウント名：「あなたのアカウント名」
• アカウントの種類："com.google"

高度な使い方

JSON 文字列を使用して、アカウント名とアカウントの種類を指定できます。

python create_contact.py '{"account_name": "your_account", "account_type": "com.google"}'

出力

スクリプトは次の内容を含む JSON オブジェクトを出力します。

• success：操作が成功したかどうかを示すブール値
• message：コマンドの出力またはエラーメッセージ

成功時の出力例：

{"success": true, "message": ""}

エラー処理

• ADB が利用できない場合、またはデバイスが接続されていない場合、スクリプトはエラーを返します
• 無効な JSON 入力の場合、エラーメッセージが返されます
• ADB コマンドのエラーはすべて捕捉され、message フィールドに返されます

注意事項

• Android デバイスが接続され、ADB の使用が許可されていることを確認してください
• コマンドの実行中は、デバイスの画面のロックを解除しておく必要があります
• 連絡先を変更するために、追加の権限が必要なデバイスもあります

アプリとショートカット

# Get app shortcuts (with pagination)
phone-cli shortcuts --package "com.example.app"