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.
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)