mcp-linux-desktop

<p align="center"> <img src="docs/banner.svg" alt="MCP Linux Desktop" width="700"/> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License"/></a> <img src="https://img.shields.io/badge/MCP-server-blue?style=flat-square" alt="MCP Server"/> <img src="https://img.shields.io/badge/Linux-GNOME%20%7C%20X11-orange?style=flat-square&logo=linux&logoColor=white" alt="Linux"/> <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square&logo=node.js&logoColor=white" alt="Node 18+"/> </p>

MCP server for full Linux desktop control — windows, mouse, keyboard, clipboard, audio, screenshots, OCR, notifications, accessibility tree, and system management. Works with any MCP-compatible AI agent.

Setup

cd mcp-linux-desktop
npm install

Add to your MCP config:

{
  "mcpServers": {
    "linux-desktop": {
      "command": "node",
      "args": ["/path/to/mcp-linux-desktop/server.js"]
    }
  }
}

Tools

Window Management

Tool	Description
window_list	List all open windows with IDs, names, geometry
window_focus	Focus a window by ID or name
window_close	Close a window
window_minimize	Minimize a window
window_resize	Resize and/or move a window

Mouse & Keyboard

Tool	Description
mouse_move	Move cursor to coordinates
mouse_click	Click (left/right/middle, single/double)
mouse_scroll	Scroll in any direction
mouse_drag	Drag from one position to another
mouse_location	Get current cursor position
keyboard_type	Type text
keyboard_key	Press key combo (e.g. ctrl+a, alt+Tab)

Apps & Files

Tool	Description
app_launch	Launch an application by name or command
app_list	List running graphical applications
file_open	Open a file or URL with its default app

Clipboard

Tool	Description
clipboard_read	Read clipboard contents
clipboard_write	Write text to clipboard

Audio

Tool	Description
volume_get	Get current volume and mute status
volume_set	Set volume (0-100) or toggle mute

Screen

Tool	Description
screenshot	Screenshot the screen or a region
screen_observe	Screenshot + screen metadata (resolution, active window, mouse position)
ocr_screen	Screenshot a region and extract text via OCR

Accessibility

Tool	Description
ui_elements	Read interactive UI elements (buttons, fields, menus) with screen coordinates via AT-SPI

System

Tool	Description
system_info	CPU, RAM, disk, uptime
process_list	List processes (optional name filter)
process_kill	Kill a process by PID or name
notify	Send a desktop notification
brightness_get	Get screen brightness
dbus_call	Call a DBus method (GNOME shell, systemd, etc.)

System dependencies

Required:

• Node.js 18+
• xdotool — window/mouse/keyboard control
• xclip — clipboard (X11)
• Python 3 + Pillow — screenshots

Optional:

• wl-paste / wl-copy — clipboard on Wayland
• tesseract-ocr + tesseract-ocr-fra — OCR
• notify-send — desktop notifications
• wpctl or pactl — audio control
• gdbus — DBus calls
• PyGObject + AT-SPI — accessibility tree (ui_elements)

Install on Ubuntu/Debian:

sudo apt install xdotool xclip python3-pil tesseract-ocr tesseract-ocr-fra \
  libnotify-bin pipewire-pulse gir1.2-atspi-2.0

Environment variables

Variable	Default	Description
DISPLAY	:1	X11 display to target