Telefon-MCP-Plugin

📱 Telefon-MCP-Plugin

🌟 Ein leistungsstarkes MCP-Plugin, mit dem Sie Ihr Android-Telefon problemlos über ADB-Befehle steuern können.

Beispiel

Basierend auf dem heutigen Wetter durch den Browser, automatisch Netease-Musik auswählen und abspielen, keine Bestätigung erforderlich
Rufen Sie Hao über die Kontakte an. Wenn er nicht antwortet, senden Sie ihm eine SMS mit der Aufforderung, in den Besprechungsraum 101 zu kommen.

⚡ Schnellstart

📥 Installation

# 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

🔧 Konfiguration

Konfiguration des KI-Assistenten

Konfigurieren Sie in Ihrer KI-Assistentenkonfiguration (Cursor, Trae, Claude usw.):

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

Alternativ, wenn Sie mit pip installiert haben:

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

Wichtig : Der Pfad /usr/local/bin/python in der obigen Konfiguration ist der Pfad zum Python-Interpreter. Sie müssen ihn entsprechend dem tatsächlichen Python-Installationsort auf Ihrem System anpassen. So finden Sie den Python-Pfad auf verschiedenen Betriebssystemen:
Linux/macOS : Führen Sie den folgenden Befehl im Terminal aus:
which python3
oder
which python
Windows : In der Eingabeaufforderung (CMD) ausführen:
where python
Oder in PowerShell:
(Get-Command python).Path
Stellen Sie sicher, dass Sie /usr/local/bin/python in der Konfiguration durch den vollständigen Pfad ersetzen. Unter Windows könnte dies beispielsweise C:\Python39\python.exe sein.

Hinweis : Platzieren Sie diese Konfiguration für Cursor in ~/.cursor/mcp.json

Verwendung:

Verwenden Sie Befehle direkt in Claudes Konversation, zum Beispiel:
Please call contact hao

⚠️ Vor der Verwendung sicherstellen:

ADB ist ordnungsgemäß installiert und konfiguriert
USB-Debugging ist auf Ihrem Android-Gerät aktiviert
Das Gerät ist über USB mit dem Computer verbunden

🎯 Hauptfunktionen

📞 Anruffunktionen : Anrufe tätigen, Anrufe beenden, eingehende Anrufe entgegennehmen
💬 Messaging : Senden und Empfangen von SMS, Erhalten von Rohnachrichten
👥 Kontakte : Greifen Sie auf Telefonkontakte zu, erstellen Sie neue Kontakte mit automatisierter UI-Interaktion
📸 Medien : Screenshots, Bildschirmaufnahme, Mediensteuerung
📱 Apps : Anwendungen starten, bestimmte Aktivitäten mit Absichten starten, installierte Apps auflisten, Apps beenden
🔧 System : Fensterinformationen, App-Verknüpfungen
🗺️ Karten : Suche nach POIs mit Telefonnummern
🖱️ UI-Interaktion : Tippen, wischen, Text eingeben, Tasten drücken
🔍 UI-Inspektion : Suchen Sie Elemente nach Text, ID, Klasse oder Beschreibung
🤖 UI-Automatisierung : Auf Elemente warten, scrollen, um Elemente zu finden
🧠 Bildschirmanalyse : Strukturierte Bildschirminformationen und einheitliche Interaktion
🌐 Webbrowser : Öffnen Sie URLs im Standardbrowser des Geräts
🔄 UI-Überwachung : Überwachen Sie UI-Änderungen und warten Sie, bis bestimmte Elemente erscheinen oder verschwinden

🛠️ Voraussetzungen

Python 3.7+
Android-Gerät mit aktiviertem USB-Debugging
ADB-Tools

📋 Grundlegende Befehle

Gerät & Verbindung

# Check device connection
phone-cli check

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

Kommunikation

# 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"

Medien & Apps

# 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

Bildschirmanalyse und Interaktion

# 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

Standort & Karten

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

📚 Erweiterte Nutzung

App- und Aktivitätsstart

Das Plugin bietet mehrere Möglichkeiten zum Starten von Apps und Aktivitäten:

Nach App-Namen (zwei Methoden):
# 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
Nach Paketnamen (zwei Methoden):
# 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
Nach Paket und Aktivität (zuverlässigste Methode):
# This method works on all devices phone-cli launch com.android.dialer/com.android.dialer.DialtactsActivity

Hinweis : Wenn bei den Befehlen app oder open_app Probleme auftreten, verwenden Sie für einen möglichst zuverlässigen Betrieb immer den launch mit dem vollständigen Komponentennamen (Paket/Aktivität).

Kontakterstellung mit UI-Automatisierung

Das Plugin bietet eine Möglichkeit, Kontakte durch UI-Interaktion zu erstellen:

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

Dieser Befehl führt Folgendes aus:

Öffnen Sie die Kontakte-App
Navigieren Sie zur Kontakterstellungsoberfläche
Füllen Sie die Felder für Name und Telefonnummer aus
Den Kontakt automatisch speichern

Bildschirmbasierte Automatisierung

Die einheitliche Bildschirminteraktionsschnittstelle ermöglicht intelligenten Agenten Folgendes:

Bildschirme analysieren : Erhalten Sie eine strukturierte Analyse von UI-Elementen und Text
Entscheidungen treffen : Basierend auf erkannten UI-Mustern und verfügbaren Aktionen
Interaktionen durchführen : Durch ein einheitliches Parametersystem

UI-Überwachung und -Automatisierung

Das Plugin bietet leistungsstarke UI-Überwachungsfunktionen zum Erkennen von Schnittstellenänderungen:

Grundlegende UI-Überwachung :
# Monitor any UI changes with custom interval (seconds) phone-cli monitor-ui --interval 0.5 --duration 30
Warten Sie, bis bestimmte Elemente angezeigt werden :
# 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"
Monitorelemente verschwinden :
# Wait for text to disappear phone-cli monitor-ui --watch-for text_disappears --text "Loading..."
Erhalten Sie detaillierte Berichte zu UI-Änderungen :
# Get raw JSON data with all UI change information phone-cli monitor-ui --raw

Tipp : Die UI-Überwachung ist besonders nützlich für Automatisierungsskripte, um auf den Abschluss von Ladebildschirmen zu warten oder zu bestätigen, dass Aktionen in der Benutzeroberfläche wirksam geworden sind.

📚 Detaillierte Dokumentation

Vollständige Dokumentation und Konfigurationsdetails finden Sie in unserem GitHub-Repository .

🧰 Tool-Dokumentation

Bildschirmschnittstellen-API

Das Plugin bietet eine leistungsstarke Bildschirmoberfläche mit umfassenden APIs für die Interaktion mit dem Gerät. Nachfolgend sind die wichtigsten Funktionen und ihre Parameter aufgeführt:

mit dem Bildschirm interagieren

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

Parameter:
- action : Art der Aktion („tippen“, „wischen“, „Taste“, „Text“, „suchen“, „warten“, „scrollen“)
- params : Wörterbuch mit für jeden Aktionstyp spezifischen Parametern
Gibt zurück: JSON-Zeichenfolge mit Operationsergebnissen

Beispiele:

# 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})

Bildschirm analysieren

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

Parameter:
- include_screenshot : Ob ein Base64-codierter Screenshot in das Ergebnis aufgenommen werden soll
- max_elements : Maximale Anzahl der zu verarbeitenden UI-Elemente
Gibt zurück: JSON-String mit detaillierter Bildschirmanalyse

Kontakt erstellen

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

Parameter:
- name : Der vollständige Name des Kontakts
- phone : Die Telefonnummer des Kontakts
Gibt zurück: JSON-Zeichenfolge mit Operationsergebnis
Ort: Diese Funktion befindet sich im Modul „contacts.py“ und implementiert die UI-Automatisierung zum Erstellen von Kontakten

App-Aktivität starten

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"""

Parameter:
- package_name : Der Paketname der zu startenden App
- activity_name : Die spezifische Aktivität, die gestartet werden soll (optional)
Gibt zurück: JSON-Zeichenfolge mit Operationsergebnis
Ort: Diese Funktion befindet sich im Modul „apps.py“

Startabsicht

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"""

Parameter:
- intent_action : Die auszuführende Aktion
- intent_type : Der MIME-Typ für die Absicht (optional)
- extras : Zusätzliche Daten, die mit der Absicht übergeben werden sollen (optional)
Gibt zurück: JSON-Zeichenfolge mit Operationsergebnis
Ort: Diese Funktion befindet sich im Modul „apps.py“

📄 Lizenz

Apache-Lizenz, Version 2.0

Tool zur Kontakterstellung

Dieses Tool bietet eine einfache Möglichkeit, mithilfe von ADB Kontakte auf einem Android-Gerät zu erstellen.

Voraussetzungen

Python 3.x
ADB (Android Debug Bridge) installiert und konfiguriert
Android-Gerät verbunden und für ADB autorisiert

Verwendung

Grundlegende Verwendung

Führen Sie einfach das Skript aus:

python create_contact.py

Dadurch wird ein Kontakt mit Standardwerten erstellt:

Kontoname: „你的账户名“
Kontotyp: „com.google“

Erweiterte Nutzung

Sie können einen benutzerdefinierten Kontonamen und -typ mithilfe einer JSON-Zeichenfolge angeben:

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

Ausgabe

Das Skript gibt ein JSON-Objekt aus mit:

success : Boolescher Wert, der angibt, ob der Vorgang erfolgreich war
message : jede Ausgabe oder Fehlermeldung des Befehls

Beispiel für eine Erfolgsausgabe:

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

Fehlerbehandlung

Wenn ADB nicht verfügbar ist oder das Gerät nicht verbunden ist, gibt das Skript einen Fehler zurück
Ungültige JSON-Eingabe führt zu einer Fehlermeldung
Alle ADB-Befehlsfehler werden erfasst und im Nachrichtenfeld zurückgegeben

Hinweise

Stellen Sie sicher, dass Ihr Android-Gerät verbunden und für die ADB-Nutzung autorisiert ist
Der Gerätebildschirm sollte beim Ausführen des Befehls entsperrt sein
Manche Geräte benötigen möglicherweise zusätzliche Berechtigungen zum Ändern von Kontakten

Apps und Verknüpfungen

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

Integrations