Phone

Controle seu telefone Android usando comandos ADB. Requer ferramentas ADB e um dispositivo Android com depuração USB ativada.

GitHub
246
Experimente este MCPPatrocinado

Documentação

📱 Plugin MCP Phone

Downloads

🌟 Um poderoso plugin MCP que permite controlar seu telefone Android com facilidade por meio de comandos ADB.

Exemplo

  • Com base no clima de hoje pelo navegador, selecione e reproduza automaticamente música do NetEase, sem necessidade de confirmação play_mucic_x2

  • Ligue para Hao nos contatos. Se ele não atender, envie uma mensagem de texto dizendo para ele ir para a Sala de Reunião 101. call_sms_x2

Documentação em chinês

⚡ Início Rápido

📥 Instalação

Use Python 3.10+ e uv para executar em um ambiente isolado:

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

As dependências extras mantêm as versões existentes do PyPI compatíveis com a API MCP v1 e fornecem requests, que o módulo de mapas importa. Elas são declaradas no pacote de origem atualizado, mas são necessárias para versões mais antigas.

Para uma instalação persistente com uv:

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

Ou use o ambiente virtual integrado do Python e pip no Linux/macOS:

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

No Windows, crie o ambiente com py -3 -m venv .venv, depois use .venv\Scripts\python.exe e .venv\Scripts\phone-cli.exe em vez dos caminhos .venv/bin/ acima.

No Debian/Ubuntu, um erro externally-managed-environment significa que o Python do sistema é gerenciado pelo SO. Use uvx ou um ambiente virtual; não o ignore com sudo pip ou --break-system-packages. Se venv não estiver disponível, instale python3-venv com o gerenciador de pacotes do seu sistema primeiro.

🔧 Configuração

Configuração do Assistente de IA

Configure no seu assistente de IA (Cursor, Trae, Claude, etc.):

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

Alternativamente, se você instalou com pip:

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

Importante: Use o caminho absoluto para o Python dentro do ambiente virtual onde você instalou phone-mcp, não o Python do sistema. No Linux/macOS, este é /absolute/path/to/.venv/bin/python; no Windows, use C:\path\to\.venv\Scripts\python.exe (escape as barras invertidas como \\ em JSON). Você não precisa ativar o ambiente antes de iniciar seu assistente de IA.

Nota: Para Cursor, coloque esta configuração em ~/.cursor/mcp.json

Uso:

  • Use comandos diretamente na conversa do Claude, por exemplo: 
    Please call contact hao

⚠️ Antes de usar, certifique-se de que:

  • O ADB está instalado e configurado corretamente
  • A depuração USB está habilitada no seu dispositivo Android
  • O dispositivo está conectado ao computador via USB

🎯 Principais Recursos

  • 📞 Funções de Chamada: Fazer chamadas, encerrar chamadas, receber chamadas recebidas
  • 💬 Mensagens: Enviar e receber SMS, obter mensagens brutas
  • 👥 Contatos: Acessar contatos do telefone, criar novos contatos com interação automatizada de interface
  • 📸 Mídia: Capturas de tela, gravação de tela, controle de mídia
  • 📱 Aplicativos: Iniciar aplicativos, iniciar atividades específicas com intents, listar aplicativos instalados, encerrar aplicativos
  • 🔧 Sistema: Informações de janela, atalhos de aplicativos
  • 🗺️ Mapas: Pesquisar POIs com números de telefone
  • 🖱️ Interação de Interface: Tocar, deslizar, digitar texto, pressionar teclas
  • 🔍 Inspeção de Interface: Encontrar elementos por texto, ID, classe ou descrição
  • 🤖 Automação de Interface: Aguardar elementos, rolar para encontrar elementos
  • 🧠 Análise de Tela: Informações estruturadas de tela e interação unificada
  • 🌐 Navegador Web: Abrir URLs no navegador padrão do dispositivo
  • 🔄 Monitoramento de Interface: Monitorar mudanças na interface e aguardar elementos específicos aparecerem ou desaparecerem

🛠️ Requisitos

  • Python 3.10+
  • Dispositivo Android com depuração USB habilitada
  • Ferramentas ADB

📋 Comandos Básicos

Dispositivo e Conexão

# Check device connection
phone-cli check

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

Comunicação

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

Mídia e Aplicativos

# 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

Análise de Tela e Interação

# 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

Localização e Mapas

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

📚 Uso Avançado

Inicialização de Aplicativos e Atividades

O plugin fornece várias maneiras de iniciar aplicativos e atividades:

  1. Por Nome do Aplicativo (Dois Métodos):

    # 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. Por Nome do Pacote (Dois Métodos):

    # 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. Por Pacote e Atividade (Método Mais Confiável):

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

Nota: Se você encontrar problemas com os comandos app ou open_app, use sempre o comando launch com o nome completo do componente (pacote/atividade) para a operação mais confiável.

Criação de Contatos com Automação de Interface

O plugin fornece uma maneira de criar contatos por meio da interação com a interface:

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

Este comando irá:

  1. Abrir o aplicativo de contatos
  2. Navegar para a interface de criação de contatos
  3. Preencher os campos de nome e número de telefone
  4. Salvar o contato automaticamente

Automação Baseada em Tela

A interface unificada de interação com a tela permite que agentes inteligentes facilmente:

  1. Analisem telas: Obtenham análise estruturada de elementos de interface e texto
  2. Tomem decisões: Com base nos padrões de interface detectados e ações disponíveis
  3. Executem interações: Por meio de um sistema de parâmetros consistente

Monitoramento e Automação de Interface

O plugin fornece poderosos recursos de monitoramento de interface para detectar mudanças na interface:

  1. Monitoramento básico de interface:

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

  2. Aguardar elementos específicos aparecerem:

    # 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. Monitorar elementos desaparecendo:

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

  4. Obter relatórios detalhados de mudanças na interface:

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

Dica: O monitoramento de interface é especialmente útil para scripts de automação aguardarem telas de carregamento terminarem ou confirmarem que as ações tiveram efeito na interface.

📚 Documentação Detalhada

Para documentação completa e detalhes de configuração, visite nosso repositório GitHub.

🧰 Documentação das Ferramentas

API de Interface de Tela

O plugin fornece uma poderosa interface de tela com APIs abrangentes para interagir com o dispositivo. Abaixo estão as principais funções e seus parâmetros:

interact_with_screen

async def interact_with_screen(action: str, params: Dict[str, Any] = None) -> str:
    """Execute screen interaction actions"""
  • Parâmetros:
    • action: Tipo de ação ("tap", "swipe", "key", "text", "find", "wait", "scroll")
    • params: Dicionário com parâmetros específicos para cada tipo de ação
  • Retorna: String JSON com resultados da operação

Exemplos:

# 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"""
  • Parâmetros:
    • include_screenshot: Se deve incluir captura de tela codificada em base64 no resultado
    • max_elements: Número máximo de elementos de interface a processar
  • Retorna: String JSON com análise detalhada da tela

create_contact

async def create_contact(name: str, phone: str) -> str:
    """Create a new contact with the given name and phone number"""
  • Parâmetros:
    • name: O nome completo do contato
    • phone: O número de telefone do contato
  • Retorna: String JSON com resultado da operação
  • Localização: Esta função está no módulo 'contacts.py' e implementa automação de interface para criar contatos

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"""
  • Parâmetros:
    • package_name: O nome do pacote do aplicativo a iniciar
    • activity_name: A atividade específica a iniciar (opcional)
  • Retorna: String JSON com resultado da operação
  • Localização: Esta função está no módulo '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"""
  • Parâmetros:
    • intent_action: A ação a executar
    • intent_type: O tipo MIME para o intent (opcional)
    • extras: Dados extras a passar com o intent (opcional)
  • Retorna: String JSON com resultado da operação
  • Localização: Esta função está no módulo 'apps.py'

📄 Licença

Apache License, Versão 2.0

Ferramenta de Criação de Contatos

Esta ferramenta fornece uma maneira simples de criar contatos em um dispositivo Android usando ADB.

Pré-requisitos

  • Python 3.x
  • ADB (Android Debug Bridge) instalado e configurado
  • Dispositivo Android conectado e autorizado para ADB

Uso

Uso Básico

Simplesmente execute o script:

python create_contact.py

Isso criará um contato com valores padrão:

  • Nome da conta: "你的账户名"
  • Tipo de conta: "com.google"

Uso Avançado

Você pode fornecer nome e tipo de conta personalizados usando uma string JSON:

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

Saída

O script gera um objeto JSON com:

  • success: booleano indicando se a operação foi bem-sucedida
  • message: qualquer mensagem de saída ou erro do comando

Exemplo de saída bem-sucedida:

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

Tratamento de Erros

  • Se o ADB não estiver disponível ou o dispositivo não estiver conectado, o script retornará um erro
  • Entrada JSON inválida resultará em uma mensagem de erro
  • Quaisquer erros de comando ADB serão capturados e retornados no campo de mensagem

Notas

  • Certifique-se de que seu dispositivo Android esteja conectado e autorizado para uso do ADB
  • A tela do dispositivo deve estar desbloqueada ao executar o comando
  • Alguns dispositivos podem exigir permissões adicionais para modificar contatos

Aplicativos e Atalhos

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