English Français العربية

Gnome Desktop MCP

Community Productivity

GNOME desktop automation via D-Bus: screenshots, window management, mouse and keyboard input, clipboard, workspaces and notifications on GNOME 45 to 49.

Source code Documentation

What can you do with Gnome Desktop MCP?

  • 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

Install

The installation steps are in the documentation below. Documentation

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Gnome-MCP
  2. Why
  3. Features
  4. Requirements
  5. Installation
  6. Claude Code Configuration
  7. Tools
  8. Privacy
  9. Architecture
  10. Development
  11. License

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
ToolDescription
screenshotFull screen capture
screenshot_windowCapture a specific window
screenshot_areaCapture a rectangular region
pick_colorGet pixel color at coordinates
cleanup_screenshotsRemove temp screenshot files
Windows
ToolDescription
list_windowsList all open windows
get_windowGet detailed window properties
focus_windowFocus and raise a window
move_resize_windowMove and resize a window
minimize_window / unminimize_windowMinimize/restore
maximize_window / unmaximize_windowMaximize/restore
close_windowClose a window
list_workspacesList all workspaces
activate_workspaceSwitch workspace
Input
ToolDescription
key_pressPress a single key ("Return", "F5", "a")
key_comboKey combination ("Ctrl+Alt+t")
type_textType text character by character
mouse_moveMove mouse to coordinates
mouse_clickClick at coordinates
mouse_double_clickDouble-click
mouse_down / mouse_upPress/release mouse button
mouse_dragDrag from point A to point B
mouse_scrollScroll at coordinates
Utility
ToolDescription
pingCheck extension is alive
get_enabled / set_enabledCheck/toggle automation
get_monitorsList 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 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

Frequently asked questions

What is Gnome Desktop MCP?

GNOME desktop automation via D-Bus: screenshots, window management, mouse and keyboard input, clipboard, workspaces and notifications on GNOME 45 to 49.

How do I install Gnome Desktop MCP?

Follow the installation steps in its documentation, shown on this page and in its repository.

Is Gnome Desktop MCP open source?

Yes. Its code is on GitHub under the GPL-3.0 license.

Who maintains Gnome Desktop MCP?

It is published by sbuysse. AI.tn lists it but does not maintain or endorse it.

From the community awesome-mcp-servers lists and the project's GitHub repository. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.