電話MCPプラグイン

📱 電話MCPプラグイン

🌟 ADB コマンドを通じて Android スマートフォンを簡単に制御できる強力な MCP プラグイン。

例

ブラウザの今日の天気に基づいて、NetEase Musicを自動的に選択して再生します。確認は不要です。
連絡先からハオに電話をかけてください。出ない場合は、会議室101に来るようにテキストメッセージを送信してください。

⚡ クイックスタート

📥 インストール

# Run directly with uvx (recommended, part of uv, no separate installation needed)
uvx phone-mcp

# Or install with uv
uv pip install phone-mcp

# Or install with pip
pip install phone-mcp

🔧 構成

AIアシスタントの設定

AI アシスタント構成 (Cursor、Trae、Claude など) で構成します。

{
    "mcpServers": {
        "phone-mcp": {
            "command": "uvx",
            "args": [
                "phone-mcp"
            ]
        }
    }
}

あるいは、pip を使用してインストールした場合:

{
    "mcpServers": {
        "phone-mcp": {
            "command": "/usr/local/bin/python",
            "args": [
                "-m",
                "phone_mcp"
            ]
        }
    }
}

重要：上記の設定におけるパス/usr/local/bin/python Pythonインタープリターへのパスです。システム上の実際のPythonインストール場所に合わせて変更する必要があります。各オペレーティングシステムでのPythonパスの確認方法は以下の通りです。
Linux/macOS : ターミナルで次のコマンドを実行します。
which python3
または
which python
Windows : コマンドプロンプト (CMD) で実行:
where python
または PowerShell の場合:
(Get-Command python).Path
設定内の/usr/local/bin/pythonフルパスに置き換えてください。たとえば、Windows ではC:\Python39\python.exeになります。

注: カーソルの場合、この設定を~/.cursor/mcp.jsonに配置します。

使用法：

Claude の会話で直接コマンドを使用します。例:
Please call contact hao

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

ADBが適切にインストールされ、設定されている
AndroidデバイスでUSBデバッグが有効になっています
デバイスはUSB経由でコンピューターに接続されています

🎯 主な機能

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

🛠️ 要件

Python 3.7以上
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

📚 高度な使用法

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

プラグインは、アプリやアクティビティを起動するための複数の方法を提供します。

アプリ名別（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つの方法）:
# 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
パッケージとアクティビティ別（最も信頼性の高い方法）：
# 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"

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

連絡先アプリを開く
連絡先作成インターフェースに移動する
名前と電話番号の欄に記入してください
連絡先を自動的に保存する

スクリーンベースの自動化

統合された画面インタラクションインターフェースにより、インテリジェントエージェントは次のことを簡単に実行できます。

画面を分析: UI要素とテキストの構造化された分析を取得します
決定を下す:検出されたUIパターンと利用可能なアクションに基づいて
インタラクションの実行：一貫したパラメータシステムを通じて

UIの監視と自動化

このプラグインは、インターフェースの変更を検出するための強力な UI 監視機能を提供します。

基本的なUI監視:
# Monitor any UI changes with custom interval (seconds) phone-cli monitor-ui --interval 0.5 --duration 30
特定の要素が表示されるまで待ちます:
# 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"
消えるモニター要素:
# Wait for text to disappear phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
詳細なUI変更レポートを取得します。
# Get raw JSON data with all UI change information phone-cli monitor-ui --raw

ヒント: UI 監視は、読み込み画面が完了するまで待機したり、UI でアクションが有効になったことを確認したりする自動化スクリプトに特に役立ちます。

📚 詳細なドキュメント

完全なドキュメントと構成の詳細については、 GitHub リポジトリをご覧ください。

🧰 ツールのドキュメント

スクリーンインターフェースAPI

このプラグインは、デバイスと連携するための包括的なAPIを備えた強力な画面インターフェースを提供します。主な機能とそのパラメータは以下のとおりです。

画面とのやり取り

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

パラメータ:
- action : アクションの種類（「タップ」、「スワイプ」、「キー」、「テキスト」、「検索」、「待機」、「スクロール」）
- 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})

分析画面

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文字列

連絡先を作成

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 自動化を実装します。

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

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' モジュールにあります

起動意図

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 ライセンスバージョン 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コマンドのエラーはすべてキャプチャされ、メッセージフィールドに返されます。

注記

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

アプリとショートカット

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

Integrations