Gnome Desktop MCP

What sbuysse/gnome-desktop-mcp MCP server does

The sbuysse/gnome-desktop-mcp MCP server gives an MCP client control and visibility over a local GNOME Wayland desktop. Its tool set covers screen capture, window discovery and manipulation, workspace switching, keyboard and mouse events, monitor geometry, and automation-state checks. The supplied listing also describes clipboard operations and system notifications as supported desktop capabilities.

Typical uses include checking what is visible on screen, focusing or rearranging an application, switching to another workspace, entering text, clicking controls, scrolling, or dragging items. Screenshots can be taken for the whole display, a selected window, or a rectangular area, and pixel colors can be read at coordinates.

How it works

The architecture has two local components. A Python MCP server receives tool calls from an MCP client and translates them into D-Bus method calls. A GNOME Shell extension runs inside the compositor and publishes the desktop automation API on the session bus under io.github.gnomemcp.DesktopAutomation.

Running inside GNOME Shell is important for Wayland sessions, where ordinary external processes cannot freely capture the screen or inject input. The extension uses GNOME Shell and Clutter APIs for screenshots, window operations, and virtual keyboard or mouse input.

The extension includes a first-use consent prompt, a top-bar status indicator, and a master enable/disable control. When automation is disabled, its D-Bus methods are blocked. The session-bus trust model allows local user processes to call the API, so this should be treated as local desktop control rather than a remotely isolated service.

Setup and configuration

The documented environment requires GNOME Shell 45–49 on Wayland and Python 3.12 or newer. The repository installation path clones the project, runs ./install.sh, requires logging out and back in, and then enables the extension with:

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

The MCP component can also be installed from PyPI with pip install gnome-desktop-mcp. After installation, an MCP client can launch the gnome-desktop-mcp executable. The README shows a Claude Code configuration using that executable in ~/.claude/settings.json.

Tools and capabilities

The available tools are grouped into several operational areas:

• Capture full screens, individual windows, or screen regions; sample a pixel; and remove temporary screenshot files.
• List windows, inspect window properties, focus windows, move or resize them, minimize or restore them, maximize or restore them, and close them.
• List workspaces and activate a selected workspace.
• Press individual keys, send key combinations, type text one character at a time, and move, click, double-click, press, release, drag, or scroll the mouse.
• Check whether the extension responds, read or change the automation switch, and list monitor geometry.

These tools operate on coordinates, key names, window identifiers, workspaces, and other desktop state supplied by the client. The sbuysse/gnome-desktop-mcp MCP server therefore fits workflows that can reason from screenshots and state queries before issuing input or window-management actions.

Limitations and notes

This project targets GNOME Shell on Wayland, specifically versions 45 through 49; the provided material does not establish support for other desktop environments, display servers, or GNOME versions. A logout and login are required after the extension installation so GNOME Shell loads it.

Automation has access to sensitive local desktop state and input. The top-bar indicator shows activity, the consent dialog appears on first use, and the extension records the names and timestamps of its last 20 method calls without recording call data. The README also notes that any local user process can access the session-bus API. The sbuysse/gnome-desktop-mcp MCP server should therefore be enabled only in a session where that trust model is acceptable.