screen-mcp

MCP local (stdio) que dá ao Claude controle da sua tela no Windows: ver, achar por imagem, clicar/digitar, gravar e repetir macros, e agendar. Sem porta exposta.

Veja SPEC.md pro design completo.

Instalar

python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

Registre no seu ~/.claude.json:

{
  "mcpServers": {
    "screen-mcp": {
      "command": "<caminho>\\.venv\\Scripts\\python.exe",
      "args": ["<caminho>\\screenmcp\\cli.py", "serve"]
    }
  }
}

Reinicie o Claude Code pra ele carregar o server. Depois é só pedir em linguagem natural ("tira um print", "acha o botão X e clica", "grava uma macro", etc.).

Ferramentas

• Ver/achar: list_monitors, screenshot, screen_info, find_image, wait_for_image
• Agir: move, click, drag, type_text, press_keys, scroll
• Macros: list_macros, record_macro, replay_macro, delete_macro
• Agendar: schedule_macro, list_schedules, unschedule

Os 4 modos

1. Ao vivo — eu uso as ferramentas vendo a tela e decidindo.
2. Macro gravada — record_macro("nome") abre uma janela; você faz as ações; F9 salva. Depois replay_macro("nome", times=N).
3. Loop com condição — wait_for_image(...) + ação, repetido (ex: refresh até um botão aparecer).
4. Agendado — schedule_macro("nome", "DAILY:09:00") cria tarefa no Agendador do Windows (MINUTE:N | HOURLY | DAILY:HH:MM | ONLOGON); roda sem o Claude presente.

Achar por imagem (o jeito robusto)

Salve um recorte (.png) do elemento em templates/ e use find_image("botao.png") → devolve x,y globais do centro pra click. Resistente a janela que se move, melhor que chutar coordenada.

Segurança

• Mouse no canto superior-esquerdo aborta tudo na hora (failsafe).
• F12 aborta um replay em andamento.
• Teto de loops + pausa entre ações. Log em logs/actions.jsonl.

Rodar standalone (sem Claude)

.venv\Scripts\python.exe screenmcp\cli.py list
.venv\Scripts\python.exe screenmcp\cli.py record minha_macro
.venv\Scripts\python.exe screenmcp\cli.py replay minha_macro --times 5

Reinstalar deps

.venv\Scripts\python.exe -m pip install -r requirements.txt

Coordenadas / multi-monitor

Tudo em coords globais do virtual desktop (monitor primário = origem; monitores à esquerda têm x negativo). Processo é per-monitor DPI aware. Em setups com DPI mista entre monitores, prefira find_image a chutar coordenada.

Licença

MIT