GNOME Desktop MCP

Gnome-MCP

Automação de desktop para GNOME Wayland via MCP. Capture telas, gerencie janelas e injete entrada de teclado/mouse a partir de assistentes de IA como Claude Code.

Claude Code  ──MCP──▶  gnome-desktop-mcp (Python)  ──D-Bus──▶  GNOME Shell Extension

Por quê

O GNOME Wayland bloqueia processos externos de capturar telas ou injetar entrada. Esta extensão roda dentro do compositor, contornando essas restrições, e expõe uma API D-Bus. O servidor MCP faz a ponte entre essa API e qualquer cliente compatível com MCP.

Recursos

• 30 ferramentas MCP: capturas de tela, gerenciamento de janelas, injeção de entrada, controle de áreas de trabalho
• Indicador de privacidade: ícone na barra superior mostra o status da conexão (vermelho = ativo, cinza = ocioso)
• Diálogo de consentimento: confirmação no primeiro uso antes de habilitar a automação
• Controle de acesso: interruptor mestre para desativar toda a automação instantaneamente

Requisitos

• GNOME Shell 45-49 (Wayland)
• Python 3.12+

Instalação

Instalação rápida (desenvolvimento)

git clone https://github.com/sbuysse/gnome-mcp.git
cd gnome-mcp
./install.sh

Em seguida, faça logout e login novamente (necessário para Wayland) e habilite:

gnome-extensions enable desktop-automation@gnomemcp.github.io

Apenas servidor MCP (via PyPI)

pip install gnome-desktop-mcp

Configuração do Claude Code

Adicione a ~/.claude/settings.json:

{
  "mcpServers": {
    "desktop-automation": {
      "command": "gnome-desktop-mcp"
    }
  }
}

Ferramentas

Capturas de tela

Ferramenta	Descrição
screenshot	Captura de tela cheia
screenshot_window	Captura de uma janela específica
screenshot_area	Captura de uma região retangular
pick_color	Obtém a cor de um pixel em coordenadas
cleanup_screenshots	Remove arquivos temporários de captura

Janelas

Ferramenta	Descrição
list_windows	Lista todas as janelas abertas
get_window	Obtém propriedades detalhadas da janela
focus_window	Foca e eleva uma janela
move_resize_window	Move e redimensiona uma janela
minimize_window / unminimize_window	Minimizar/restaurar
maximize_window / unmaximize_window	Maximizar/restaurar
close_window	Fecha uma janela
list_workspaces	Lista todas as áreas de trabalho
activate_workspace	Alterna área de trabalho

Entrada

Ferramenta	Descrição
key_press	Pressiona uma única tecla ("Return", "F5", "a")
key_combo	Combinação de teclas ("Ctrl+Alt+t")
type_text	Digita texto caractere por caractere
mouse_move	Move o mouse para coordenadas
mouse_click	Clique em coordenadas
mouse_double_click	Clique duplo
mouse_down / mouse_up	Pressionar/soltar botão do mouse
mouse_drag	Arrasta do ponto A ao ponto B
mouse_scroll	Rola em coordenadas

Utilitários

Ferramenta	Descrição
ping	Verifica se a extensão está ativa
get_enabled / set_enabled	Verifica/alterna automação
get_monitors	Lista monitores com geometria

Privacidade

• Indicador na barra superior mostra quando a automação está ativa
• Interruptor para desativar toda a automação instantaneamente
• Registro de atividades rastreia as últimas 20 chamadas de método (apenas nome + timestamp, sem dados)
• Controle de acesso D-Bus: todos os métodos são bloqueados quando desativados
• Modelo de confiança do barramento de sessão: qualquer processo de usuário local pode chamar a API (consistente com o modelo de segurança do GNOME)

Arquitetura

A extensão do GNOME Shell (desktop-automation@gnomemcp.github.io) roda dentro do compositor Wayland. Ela exporta io.github.gnomemcp.DesktopAutomation no D-Bus de sessão com acesso privilegiado a:

• Shell.Screenshot — capturas de tela silenciosas (sem diálogo de permissão)
• Meta.Window — gerenciamento de janelas
• Clutter.VirtualInputDevice — injeção de teclado/mouse

O servidor MCP em Python (gnome-desktop-mcp) traduz chamadas de ferramentas MCP em chamadas de método D-Bus via dasbus.

Desenvolvimento

# Install in development mode
pip install -e mcp-server[dev]

# Run tests
python -m pytest tests/ -v

# Watch extension logs
journalctl /usr/bin/gnome-shell -f

# Test D-Bus directly
gdbus call --session --dest org.gnome.Shell \
  --object-path /io/github/gnomemcp/DesktopAutomation \
  --method io.github.gnomemcp.DesktopAutomation.Ping

Licença

GPL-3.0