sbuysse/gnome-desktop-mcp

Desktop automation for GNOME Wayland via MCP. Take screenshots, manage windows, and inject keyboard/mouse input from AI assistants like Claude Code.

GNOME Desktop MCP server

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

Why

GNOME Wayland blocks external processes from taking screenshots or injecting input. This extension runs inside the compositor, bypassing those restrictions, and exposes a D-Bus API. The MCP server bridges that API to any MCP-compatible client.

Features

• 30 MCP tools: screenshots, window management, input injection, workspace control
• Privacy indicator: top bar icon shows connection status (red = active, grey = idle)
• Consent dialog: first-use confirmation before enabling automation
• Access gating: master kill switch to disable all automation instantly

Requirements

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

Installation

Quick install (development)

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

Then log out and back in (required for Wayland), and enable:

gnome-extensions enable [email protected]

MCP server only (from PyPI)

pip install gnome-desktop-mcp

Claude Code Configuration

Add to ~/.claude/settings.json:

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

Tools

Screenshots

Tool	Description
screenshot	Full screen capture
screenshot_window	Capture a specific window
screenshot_area	Capture a rectangular region
pick_color	Get pixel color at coordinates
cleanup_screenshots	Remove temp screenshot files

Windows

Tool	Description
list_windows	List all open windows
get_window	Get detailed window properties
focus_window	Focus and raise a window
move_resize_window	Move and resize a window
minimize_window / unminimize_window	Minimize/restore
maximize_window / unmaximize_window	Maximize/restore
close_window	Close a window
list_workspaces	List all workspaces
activate_workspace	Switch workspace

Input

Tool	Description
key_press	Press a single key ("Return", "F5", "a")
key_combo	Key combination ("Ctrl+Alt+t")
type_text	Type text character by character
mouse_move	Move mouse to coordinates
mouse_click	Click at coordinates
mouse_double_click	Double-click
mouse_down / mouse_up	Press/release mouse button
mouse_drag	Drag from point A to point B
mouse_scroll	Scroll at coordinates

Utility

Tool	Description
ping	Check extension is alive
get_enabled / set_enabled	Check/toggle automation
get_monitors	List monitors with geometry

Privacy

• Top bar indicator shows when automation is active
• Toggle switch to disable all automation instantly
• Activity log tracks last 20 method calls (name + timestamp only, no data)
• D-Bus access gating: all methods blocked when disabled
• Session bus trust model: any local user process can call the API (consistent with GNOME's security model)

Architecture

The GNOME Shell extension ([email protected]) runs inside the Wayland compositor. It exports io.github.gnomemcp.DesktopAutomation on the session D-Bus with privileged access to:

• Shell.Screenshot — silent screenshots (no permission dialog)
• Meta.Window — window management
• Clutter.VirtualInputDevice — keyboard/mouse injection

The Python MCP server (gnome-desktop-mcp) translates MCP tool calls into D-Bus method calls via dasbus.

Development

# 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

License

GPL-3.0