About sbuysse/gnome-desktop-mcp
sbuysse/gnome-desktop-mcp is an MCP server in the Browser category: bus: screenshots, window management, mouse/keyboard injection, clipboard, workspaces, and system notifications. Works on any GNOME 45–49 Linux desktop.
Install
git clone https://github.com/sbuysse/gnome-desktop-mcpThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Tools (5)
cleanup_screenshotsRemove temp screenshot files
Parameters not published.
pick_colorGet pixel color at coordinates
Parameters not published.
screenshotFull screen capture
Parameters not published.
screenshot_areaCapture a rectangular region
Parameters not published.
screenshot_windowCapture a specific window
Parameters not published.
Ask AI
Ask AI about sbuysse/gnome-desktop-mcp
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
Gnome-MCP
Desktop automation for GNOME Wayland via MCP. Take screenshots, manage windows, and inject keyboard/mouse input from AI assistants like Claude Code.
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 desktop-automation@gnomemcp.github.io
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 (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.
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
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.