<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 |