Gnome Desktop MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gnome Desktop MCP listing page.
Gnome-MCP
Desktop automation for GNOME Wayland via MCP. Take screenshots, manage windows, and inject keyboard/mouse input from AI assistants like Claude Code.
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)
Then log out and back in (required for Wayland), and enable:
MCP server only (from PyPI)
Claude Code Configuration
Add to ~/.claude/settings.json:
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 (desktop-automation@gnomemcp.github.io) 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 managementClutter.VirtualInputDevice— keyboard/mouse injection
The Python MCP server (gnome-desktop-mcp) translates MCP tool calls into D-Bus method calls via dasbus.