PocketMCP

Transforme seu telefone Android em um servidor MCP (Model Context Protocol). Agentes de IA e scripts de desktop podem chamar seu telefone para obter dados e ações ao vivo pela rede local.

GitHub
14
Experimente este MCPPatrocinado

Documentação

PocketMCP

Transforme seu telefone Android em um servidor MCP (Model Context Protocol). Agentes de IA e scripts de desktop podem acessar seu telefone para dados ao vivo e ações via LAN ou Tailscale.

Download (Pré-lançamento de Teste)

  • Última versão de teste: v1.0.0-beta.1
  • Esta versão é marcada como pré-lançamento e pode conter bugs enquanto o desenvolvimento ativo continua.

Compromisso com Código Aberto

O PocketMCP é totalmente open-source e a funcionalidade principal é gratuita. O projeto é licenciado sob MIT e contribuições da comunidade são bem-vindas.

Por que isso é útil

Casos de uso de alto valor para todos os usuários:

  1. Central de Comunicação: Envie mensagens pelo WhatsApp, Instagram, Messenger e faça chamadas do desktop
  2. Automação de Redes Sociais: Interaja com Instagram, YouTube, X/Twitter automaticamente
  3. Gerenciamento de Notificações: Monitore e responda a todas as notificações do telefone em tempo real
  4. Verificação diária de prontidão: "Qual é a minha bateria e onde está meu telefone agora?"
  5. Consulta de contatos: "Encontre o número da Alice nos meus contatos."
  6. Controle do ecossistema de apps: Inicie e gerencie 309+ aplicativos instalados
  7. Diagnóstico do telefone: Execute verificações seguras de shell sem desbloquear o telefone.

Ferramentas integradas

FerramentaDescrição
device_infoBateria, modelo, SO, rede, memória
get_locationMelhor localização recente dos provedores do dispositivo
search_contactsBuscar contatos por nome
make_callFazer chamadas telefônicas para qualquer número
send_messageEnviar mensagens via WhatsApp, Instagram, Messenger, Google Messages
send_whatsapp_business_messageEnvio dedicado do WhatsApp Business com segurança de contato
whatsapp_automationAutomação avançada do WhatsApp com controle de acessibilidade
social_mediaInterações com Instagram, YouTube, X/Twitter
app_actionsAções com presets JSON para chamadas de automação mais simples
notificationsMonitoramento e gerenciamento de notificações em tempo real
shellExecutar comandos shell com filtros de segurança e timeout
flashlightLigar/desligar/alternar lanterna e ler estado
launch_appAbrir um app instalado por pacote ou nome
list_appsListar apps instalados iniciáveis (309+ apps detectados)
global_actionInício/voltar/recentes/notificações/configurações rápidas/tela de bloqueio
scroll_screenRolar o app atual via gesto de acessibilidade
search_screenEncontrar campo de busca na tela atual e digitar consulta com segurança
tapTocar por texto visível/descrição de conteúdo ou coordenadas de tela
volume_controlLer e alterar níveis de volume de streaming
phone_alertTocar e/ou vibrar o telefone para localizá-lo rapidamente
voice_recordGravar notas de voz pelo microfone
transcribe_audioConversão de fala em texto pelo microfone ou caminho de arquivo de áudio local
transcribe_fileTranscrição direta de arquivo de áudio por caminho
transcribe_whatsapp_audioTranscrever última nota de voz do WhatsApp/WhatsApp Business
human_commandRoteador de comandos em linguagem natural entre as principais ferramentas
http_requestFazer requisições HTTP de saída pelo telefone
read_fileLer arquivos de caminhos de armazenamento permitidos

🆕 Novos Recursos (v.0+)

📞 Chamadas Telefônicas e Mensagens

  • Chamadas Diretas: Faça chamadas para qualquer número com suporte a nome de contato
  • Mensagens Multi-Plataforma: WhatsApp, Instagram, Messenger, Google Messages
  • Suporte ao WhatsApp Business: Prioriza o WhatsApp Business quando instalado
  • Integração com Deep Links: Abre apps com conteúdo pré-preenchido

🤖 Automação Avançada do WhatsApp

  • Automação Completa: Envie mensagens com seleção de contato e digitação
  • Controle Passo a Passo: Selecione contatos, digite mensagens, pressione enviar/cancelar
  • Integração com Acessibilidade: Automação completa de UI via serviço de acessibilidade
  • Business e Pessoal: Suporta ambas as variantes do WhatsApp

🌐 Interações em Redes Sociais

  • Instagram: Busca de perfil, interações com postagens (curtir, comentar, compartilhar)
  • YouTube: Busca de vídeos, curtir/não curtir/comentar em vídeos
  • X/Twitter: Busca de perfil, interações com postagens
  • Deep Links: Navegação direta para conteúdo específico

🔔 Notificações em Tempo Real

  • Monitoramento ao Vivo: Capture todas as notificações do dispositivo em tempo real
  • Dados Completos: Título, texto, app, hora, prioridade, visibilidade
  • Acesso Histórico: Notificações recentes com busca e filtros
  • Gerenciamento: Limpar histórico, verificar status, obter contagens

Modelo de Segurança

  • Autenticação por chave de API suportada via X-API-Key (recomendado).
  • Uso em rede local por padrão; use Tailscale para acesso remoto.
  • A ferramenta de shell bloqueia comandos de alto risco e impõe limites de timeout/saída.
  • Leituras de arquivo são restritas ao armazenamento do app e raízes de armazenamento externo.
  • URLs de loopback são bloqueadas em http_request.
  • Serviço de Acessibilidade: Necessário para recursos avançados de automação.
  • Acesso a Notificações: Necessário para monitoramento de notificações em tempo real.

Modelo de Confiabilidade

  • O serviço em primeiro plano do Android mantém o servidor MCP ativo.
  • O ciclo de vida iniciar/parar/status é explícito (START, STOP, QUERY_STATUS).
  • A UI reflete o estado real do serviço usando broadcasts de status.
  • Descoberta Aprimorada de Apps: Detecta 309+ apps iniciáveis (antes 25).
  • Fallbacks Elegantes: Instruções de interação manual quando a automação não é possível.

Início Rápido

1) Instalar o app

Opção A: instalar pelo APK de pré-lançamento

adb install -r PocketMCP-debug.apk

Opção B: compilar a partir do código-fonte e instalar

./gradlew assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk

2) Iniciar o servidor no app

  1. Abra o PocketMCP.
  2. Defina a porta (padrão 8080).
  3. Gere ou cole a chave de API.
  4. Inicie o servidor pelo interruptor ou botão.
  5. Copie o endpoint/configuração da seção Quick Connect.

3) Habilitar Permissões

Necessário para funcionalidade completa:

  • Localização: ACCESS_FINE_LOCATION (solicitada automaticamente na inicialização)
  • Contatos: READ_CONTACTS (solicitada automaticamente na inicialização)
  • Câmera: CAMERA (solicitada automaticamente na inicialização)
  • Telefone: permissão CALL_PHONE nas configurações do app
  • Microfone: permissão RECORD_AUDIO nas configurações do app
  • SMS: permissões SEND_SMS, READ_SMS
  • Áudio/Armazenamento: READ_MEDIA_AUDIO ou READ_EXTERNAL_STORAGE (solicitada automaticamente)
  • Notificações: Configurações > Apps > Acesso Especial > Acesso a Notificações
  • Acessibilidade: Configurações > Apps > Acesso Especial > Serviços de Acessibilidade

4) Verificar o servidor

# health
curl http://192.168.1.100:8080/health

# list tools
curl -X POST http://192.168.1.100:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Conexão com emulador (AVD do Android Studio)

Se o PocketMCP estiver rodando dentro de um emulador Android, não use 10.0.2.15 na configuração do cliente MCP do host.

Use encaminhamento de porta ADB e localhost:

powershell -ExecutionPolicy Bypass -File .\scripts\setup-emulator-mcp.ps1

Depois defina a URL do MCP para:

http://127.0.0.1:8080/mcp

Observações:

  • 10.0.2.15 é interno ao emulador (não acessível pelo host).
  • 10.0.2.2 é para emulador -> host, não host -> emulador.

Exemplo de Configuração do Cliente MCP

Use mcp-config.example.json como modelo.

{
  "mcpServers": {
    "phone": {
      "type": "streamableHttp",
      "url": "http://192.168.1.100:8080/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Ponte Stdio (para clientes MCP somente stdio)

O PocketMCP inclui uma ponte stdio reforçada em mcp-bridge/bridge.mjs que faz proxy de chamadas MCP stdio para o endpoint HTTP MCP do seu telefone.

cd mcp-bridge
npm install
node bridge.mjs --url http://192.168.1.100:8080/mcp --api-key your-api-key --verbose

Opções de configuração da ponte:

  • --url: URL MCP do telefone de destino (adiciona http:// automaticamente se ausente)
  • --api-key: chave de API enviada como X-API-Key
  • --timeout-ms: timeout por requisição (padrão 20000)
  • --tools-ttl-ms: TTL do cache de ferramentas (padrão 30000)
  • --no-tool-cache: desabilitar cache de ferramentas
  • --verbose: emitir logs detalhados da ponte no stderr

Variáveis de ambiente equivalentes:

  • POCKET_MCP_URL
  • POCKET_MCP_API_KEY
  • POCKET_MCP_TIMEOUT_MS
  • POCKET_MCP_TOOLS_TTL_MS
  • POCKET_MCP_DISABLE_TOOL_CACHE=1
  • POCKET_MCP_VERBOSE=1

Exemplo de Cliente Python

from pocket_mcp_client import PocketMCPClient

phone = PocketMCPClient("http://192.168.1.100:8080", api_key="your-api-key")

print(phone.device_info())
print(phone.list_apps(limit=25))
print(phone.notifications("list", 10))
print(phone.human_command("vibrate my phone for 5 seconds"))

O cliente Python agora inclui tentativas, exceções tipadas, validação de argumentos mais rigorosa e uma CLI:

# health check (default action)
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key

# list tools
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key --list-tools

# call one tool with JSON args
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key \
  --call send_message \
  --args '{"app":"whatsapp","phone_number":"+15551234567","message":"hello from desktop"}'

Permissões

Algumas ferramentas exigem permissões especiais ou serviços do Android:

  • Telefone (CALL_PHONE)
  • Microfone (RECORD_AUDIO)
  • SMS (SEND_SMS, READ_SMS, RECEIVE_SMS)
  • Acesso a notificações (Notification Listener)
  • Serviço de acessibilidade (para automação de UI)

Modelo de Segurança

  • Autenticação por chave de API via X-API-Key (recomendado)
  • Rede local primeiro; acesso remoto via redes privadas como Tailscale
  • Restrições de comandos shell com limites de timeout/saída
  • Restrições de caminho para leitura de arquivos
  • Bloqueio de URL de loopback para http_request

Observações de Confiabilidade

  • Executa como serviço em primeiro plano do Android
  • Ciclo de vida explícito do serviço (START, STOP, QUERY_STATUS)
  • Atualizações de broadcast de status refletidas na UI

Roadmap

  • Ferramentas de captura de câmera
  • Mais automações orientadas por acessibilidade
  • Suporte a WebSocket
  • Fluxo de pareamento com um toque
  • Fluxos de comandos por voz

Licença

MIT