Content
<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
```bash
cd mcp-linux-desktop
npm install
```
Add to your MCP config:
```json
{
"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:
```bash
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 |
