ERIUS PHONE MCP

Dá ao seu agente de IA um telefone Android real (ERIUS PHONE): leia a tela, toque, digite, abra e instale aplicativos, leia logs de falhas.

GitHub

Experimente este MCPPatrocinado

Documentação

erius-phone-mcp

Um servidor MCP que transforma seu dispositivo ERIUS PHONE em ferramentas nativas para Claude Code, Claude Desktop, Cursor ou qualquer outro cliente MCP. Um dispositivo ERIUS PHONE é um smartphone ou tablet Android real dedicado ao seu agente. Quando este servidor estiver conectado, seu agente pode:

listar seus dispositivos
ler a tela como uma árvore de acessibilidade ou uma captura de tela
tocar, pressionar longamente, digitar, deslizar e rolar
iniciar e parar aplicativos, abrir URLs e enviar intents
instalar e desinstalar APKs
obter logs de crash

O agente controla o dispositivo diretamente. Você não escreve nenhum código de integração.

Acesso antecipado: este pacote está na versão pré-1.0 (0.1.0). Nomes de ferramentas e argumentos podem mudar antes da versão 1.0.

Requisitos

Python 3.10+
Uma chave de API ERIUS PHONE. Cadastre-se em https://eriusphone.com; veja "Como obter uma chave de API" abaixo.

Instalação

Opção A: uvx (sem etapa de instalação). Se você tiver uv, seu cliente MCP pode iniciar o servidor com uvx erius-phone-mcp. O uv baixa o pacote e o mantém em seu próprio ambiente. As configurações de cliente abaixo mostram esta forma.

Opção B: pip, em seu próprio ambiente virtual para que suas dependências não entrem em conflito com seus outros projetos Python:

python3 -m venv ~/.venvs/erius-phone-mcp
~/.venvs/erius-phone-mcp/bin/pip install erius-phone-mcp

Isso instala um comando erius-phone-mcp em ~/.venvs/erius-phone-mcp/bin/erius-phone-mcp. Use esse caminho absoluto como o command na configuração do seu cliente: aplicativos GUI como Claude Desktop e Cursor geralmente não veem o PATH do seu venv. python -m erius_phone_mcp faz a mesma coisa que executar o comando.

Configuração

O servidor é configurado inteiramente por meio de variáveis de ambiente:

Variável	Obrigatória	O que é
`ERIUS_PHONE_API_KEY`	sim	Sua chave de API ERIUS PHONE. Cada requisição é autenticada com ela e limitada à sua conta.
`ERIUS_PHONE_DEFAULT_DEVICE`	não	O ID do dispositivo a ser usado quando uma chamada de ferramenta não especificar um (ex.: `vanilla`). Sem ele, o agente passa `device` em cada chamada; `list_devices` mostra os IDs.
`ERIUS_PHONE_API_URL`	não	URL base da API. Padrão `https://api.eriusphone.com`; defina apenas se fornecermos uma diferente.
`ERIUS_PHONE_TIMEOUT`	não	Tempo limite de HTTP por requisição, em segundos. Padrão `30`.

Como obter uma chave de API

Solicite acesso em https://eriusphone.com. Durante o acesso antecipado, a equipe ERIUS PHONE configura cada conta manualmente. Você receberá sua chave de API e ID(s) de dispositivo diretamente de nós. Se você se cadastrou e não recebeu resposta, envie um e-mail para info@eriusphone.com. A mesma chave também faz login no painel em https://eriusphone.com/dashboard/, que mostra seus dispositivos ao vivo.

Trate a chave como uma senha: qualquer pessoa que a tiver pode controlar seu dispositivo.

Importante: os clientes MCP iniciam este servidor como um subprocesso e, em geral, não repassam variáveis que você export no seu shell. Coloque as variáveis no bloco env do cliente, conforme mostrado abaixo.

Adicione ao seu cliente MCP

Em cada exemplo, substitua a chave e o ID do dispositivo pelos seus. Se você instalou com pip em vez de usar uvx, substitua "command": "uvx", "args": ["erius-phone-mcp"] with "command": "/home/you/.venvs/erius-phone-mcp/bin/erius-phone-mcp".

Claude Code

claude mcp add erius-phone \
  -e ERIUS_PHONE_API_KEY=your-api-key \
  -e ERIUS_PHONE_DEFAULT_DEVICE=your-device-id \
  -- uvx erius-phone-mcp

Adicione -s user para disponibilizar o servidor em todos os seus projetos, ou -s project para gravá-lo em um .mcp.json compartilhado. Não envie sua chave para um .mcp.json compartilhado. O Claude Code expande referências ${VAR} nesse arquivo, então você pode manter a chave em uma variável de ambiente:

{
  "mcpServers": {
    "erius-phone": {
      "command": "uvx",
      "args": ["erius-phone-mcp"],
      "env": {
        "ERIUS_PHONE_API_KEY": "${ERIUS_PHONE_API_KEY}",
        "ERIUS_PHONE_DEFAULT_DEVICE": "your-device-id"
      }
    }
  }
}

Execute /mcp dentro do Claude Code para verificar se erius-phone está conectado.

Claude Desktop

Edite claude_desktop_config.json (Configurações → Desenvolvedor → Editar Config). No macOS, fica em ~/Library/Application Support/Claude/; no Windows, fica em %APPDATA%\Claude\.

{
  "mcpServers": {
    "erius-phone": {
      "command": "uvx",
      "args": ["erius-phone-mcp"],
      "env": {
        "ERIUS_PHONE_API_KEY": "your-api-key",
        "ERIUS_PHONE_DEFAULT_DEVICE": "your-device-id"
      }
    }
  }
}

Se o Claude Desktop não encontrar uvx, coloque o caminho absoluto em command (which uvx). Saia e reabra o Claude Desktop completamente após editar.

Cursor

Coloque o mesmo bloco mcpServers em ~/.cursor/mcp.json para usá-lo em todos os projetos, ou em .cursor/mcp.json para um único projeto. Em seguida, ative erius-phone em Configurações do Cursor → MCP.

Qualquer outro cliente MCP

O servidor fala MCP via stdio. Aponte seu cliente para uvx erius-phone-mcp, or at the erius-phone-mcp executável e passe as variáveis de ambiente acima.

Ferramentas

Toda ferramenta que age em um dispositivo aceita um argumento opcional device. Se você omitir, a ferramenta usa ERIUS_PHONE_DEFAULT_DEVICE.

Conta e dispositivos

Ferramenta	Descrição
`whoami`	Qual conta e chave este servidor está usando e os IDs de dispositivos que pode acessar. Uma forma rápida de verificar se a chave funciona.
`list_devices`	Todos os dispositivos que sua chave pode acessar, com status ao vivo (inicializado, versão do Android, tamanho da tela).
`get_device`	Status completo de um dispositivo, incluindo o aplicativo atualmente em primeiro plano.

Vendo a tela

Ferramenta	Descrição
`snapshot`	Instantâneo da árvore de acessibilidade da tela atual: cada elemento visível com seu texto, função e um `ref` que você pode passar para tocar/digitar/rolar. As referências são redefinidas a cada instantâneo.
`screenshot`	PNG da tela na resolução nativa, retornado como conteúdo de imagem MCP, para que o modelo veja a tela diretamente.
`foreground`	Apenas o aplicativo em primeiro plano (pacote, atividade) e se um diálogo de crash está sendo exibido.
`wait_for_text`	Aguarda até que algum texto apareça na tela, por até `timeout_ms` (máx. 120000). Retorna o instantâneo que viu.

Agindo na tela

Ferramenta	Descrição
`tap`	Toque por `ref`, por `text`/`content_desc` visível, ou em `x`,`y` pixels brutos.
`long_press`	Pressione longo por `ref`, por `text`/`content_desc`, ou em `x`,`y` (tempo de espera opcional `ms`).
`type_text`	Digite em um campo. Pode tocar em um `ref`/`text_target` primeiro, `clear` o campo e pressionar Enter depois.
`press_key`	back, home, enter, delete, tab, escape, up, down, left, right, space, power, volup, voldown, recent, menu, wakeup ou um keycode numérico.
`swipe`	Deslize entre dois pontos em pixels do dispositivo.
`scroll`	Role um contêiner para cima/baixo/esquerda/direita. Passe o `ref` do próprio ScrollView/List, não de uma linha dentro dele.

Aplicativos

Ferramenta	Descrição
`launch_app`	Inicie um aplicativo instalado pelo nome do pacote (ex.: `com.android.settings`).
`open_url`	Abra uma URL http/https/market, opcionalmente em um aplicativo específico.
`send_intent`	Inicie uma atividade com qualquer ação de intent, ex.: `android.settings.WIFI_SETTINGS`, com dados, pacote, componente e extras opcionais.
`stop_app`	Force a parada de um aplicativo.
`list_apps`	Aplicativos instalados; `third_party_only=True` para apenas os instalados pelo usuário.
`install_apk`	Envie e instale um APK de um arquivo na máquina que executa este servidor. Retorna nome do pacote, versão e se a instalação foi bem-sucedida.
`uninstall_app`	Desinstale um aplicativo pelo nome do pacote.
`get_crash_log`	O buffer de log de crash do dispositivo (`logcat -b crash`). Use após um aplicativo travar para ver o stack trace real.

Exemplo rápido

Quando o servidor estiver conectado, peça ao seu agente em linguagem natural, ex.: "Liste meus dispositivos ERIUS, vá para a tela inicial e abra Contatos." Veja o que acontece nos bastidores. As saídas abaixo são reais, levemente editadas.

1. Encontre seu dispositivo. O agente chama list_devices:

{"devices": [
  {"id": "vanilla", "description": "redroid Android 13, no Google services", "state": "device",
   "bootCompleted": true, "android": "13", "sdk": 33, "screen": {"width": 720, "height": 1280}},
  {"id": "tablet1", "form": "tablet", "description": "redroid Android 13 (vanilla, tablet)", "state": "device",
   "bootCompleted": true, "android": "13", "sdk": 33, "screen": {"width": 1600, "height": 2560}}
]}

2. Vá para a tela inicial e olhe a tela. press_key(key="home", device="vanilla") retorna {"ok": true}, então snapshot(device="vanilla") retorna o aplicativo em primeiro plano mais esta árvore:

- Group
  - ScrollView [ref=1]
    - Group
      - AppWidgetHostView (Search)
        ...
      - Text [ref=4] "Gallery" (Gallery)
  - View (Home)
  - Group
    - Text [ref=5] "Contacts" (Contacts)
    - Text [ref=6] "WebView Browser Tester" (WebView Browser Tester)
    - Text [ref=7] "Camera" (Camera)

3. Toque em algo. tap(device="vanilla", ref="5"), tap(device="vanilla", text="Contacts") and tap(device="vanilla", x=102, y=1116) todos abrem Contatos e retornam {"ok": true}. Após qualquer ação, tire um novo snapshot, pois as referências são válidas apenas até a próxima.

4. Verifique o resultado. foreground(device="vanilla") agora relata o aplicativo Contatos, e screenshot(device="vanilla") retorna a tela como uma imagem que seu agente vê diretamente.

Instalando um APK para QA funciona da mesma forma:

install_apk(device="vanilla", apk_path="/path/to/app.apk")
→ {"ok": true, "package": "com.erius.dashtest", "versionName": "1.0", "label": "ERIUS Dash Test",
   "adbOutput": "Performing Streamed Install\nSuccess", "ms": 94, ...}

Dicas e limites

Erros são repassados. Se a API recusar uma ação, a chamada da ferramenta falha com o código e a mensagem de erro da API, ex.: HTTP 404: SelectorNotFound ... nothing on screen matches {"text": "..."} or HTTP 422: no_launcher_activity. O agente pode ler a mensagem e ajustar.
Digitar exige um campo pronto. Teclas enviadas enquanto um campo ainda está abrindo são perdidas. Se tocar em um campo abrir uma nova tela (como a busca das Configurações do Android), toque nele, aguarde com snapshot/wait_for_text, então chame type_text sem um alvo. Verifique o resultado com snapshot.
Digitação apenas ASCII. type_text suporta apenas ASCII imprimível (uma limitação do adb): sem emojis, caracteres acentuados ou scripts não latinos.
Role pelo contêiner. scroll precisa da referência do contêiner rolável (uma linha ScrollView/List no instantâneo). Se o contêiner não tiver referência, use swipe.
Capturas de tela custam contexto. Uma captura de smartphone (720×1280) tem ~50–700 KB; uma captura de tablet (1600×2560) pode ter vários MB. Prefira snapshot (texto, muito menor) e tire capturas apenas quando precisar de pixels.
install_apk lê um arquivo local. O caminho está na máquina que executa erius-phone-mcp, não no telefone. O APK é transmitido do disco e enviado por completo em cada chamada.
Um processo de servidor = uma chave de API. Para usar várias contas, adicione várias entradas de servidor com nomes e chaves diferentes.
Limites de taxa. A API permite cerca de 30 requisições por segundo por IP e enfileira no máximo 8 requisições por dispositivo; além disso, você recebe HTTP 429.

Solução de problemas

ERIUS_PHONE_API_KEY is not set: a variável não chegou ao processo do servidor. Coloque-a no bloco env do cliente, não apenas no seu shell. O servidor também imprime um aviso sobre isso no stderr na inicialização, que aparece nos logs MCP do seu cliente.
no device id given and ERIUS_PHONE_DEFAULT_DEVICE is not set: passe device= na chamada da ferramenta ou defina ERIUS_PHONE_DEFAULT_DEVICE. list_devices mostra seus IDs.
HTTP 401: a chave está errada ou revogada. HTTP 403: o ID do dispositivo não existe ou não está na sua conta. Execute whoami para ver quais dispositivos sua chave pode usar.
HTTP 503 device_offline: o dispositivo está reiniciando. Tente novamente em breve.
could not reach the ERIUS PHONE API at ...: a URL está errada ou a API está inacessível da sua máquina. Verifique ERIUS_PHONE_API_URL e aumente ERIUS_PHONE_TIMEOUT se você estiver em uma conexão lenta.

Licença

MIT. O texto completo da licença está no arquivo LICENSE incluído no pacote.