Skip to content
Back to search

linux-computer-use-mcp

Let Claude see and control your Linux desktop live - MCP server for X11 & Wayland (GNOME, KDE, Sway, Hyprland)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dhakseshr--linux-computer-use-mcp/badge.svg)](/listings/dhakseshr--linux-computer-use-mcp)

HTML

<a href="/listings/dhakseshr--linux-computer-use-mcp"><img src="/api/listings/dhakseshr--linux-computer-use-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. System packages

**X11**

sudo apt install xdotool          # Debian / Ubuntu
sudo dnf install xdotool          # Fedora
sudo pacman -S xdotool            # Arch

**Wayland**: install a screenshot tool for your desktop, plus `dotool`:

# Ubuntu / Debian (GNOME)
sudo apt install gnome-screenshot
# KDE: spectacle   ·   Sway/Hyprland: grim
# Arch: sudo pacman -S grim  /  yay -S dotool

`dotool` is packaged in the AUR and some other distros. If yours doesn't have it, build it from [sr.ht/~geb/dotool](https://git.sr.ht/~geb/dotool) (`./build.sh && sudo ./build.sh install`; needs Go). `ydotool` ≥ 1.0 with `ydotoold` running also works, but its pointer positioning is less precise (it moves relatively, so pointer acceleration affects it).

Then allow virtual input once, and **log out and back in**:

linux-computer-use-mcp setup-wayland --yes

2. The server

pipx install git+https://github.com/dhakseshr/linux-computer-use-mcp
# or with uv:
uv tool install git+https://github.com/dhakseshr/linux-computer-use-mcp

3. Check it

linux-computer-use-mcp doctor

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 204 lines
  1. # linux-computer-use-mcp
  2. **Let Claude see and control your Linux desktop, live.** Claude takes screenshots, and you watch the
  3. real mouse pointer glide across your screen, click, scroll, drag, type and press shortcuts.
  4. The official Claude desktop app supports Computer Use on macOS and Windows, but not (yet) on Linux.
  5. This project is an open-source [MCP](https://modelcontextprotocol.io) server that fills the gap. It works with
  6. the Claude desktop app for Linux, Claude Code, and any other MCP client.
  7. > Community project, not affiliated with or endorsed by Anthropic.
  8. ## Features
  9. - **Works on X11 and Wayland**: GNOME, KDE Plasma, Sway, Hyprland, river, Wayfire, XFCE, Cinnamon, MATE…
  10. - **You can watch it work**: the pointer glides smoothly to each target (120 fps eased motion) and text is typed key by key.
  11. - **Fast**:
  12. - Every action returns a fresh screenshot as soon as the screen *stops changing*, so there are no guessed waits and no separate screenshot call.
  13. - `batch` runs a whole sequence (click → type → Enter) in one call.
  14. - On X11 the mouse goes straight through XTEST in-process (a click takes ~3 ms), and screenshots are compact JPEGs.
  15. - **Full toolset**: `screenshot`, `click` (left/right/middle, double/triple, with modifier keys),
  16. `move_mouse`, `drag`, `scroll`, `type_text`, `press_key` (`ctrl+s`, `alt+Tab`, `super`…), `hold_key`,
  17. `batch`, `wait` (returns early once the screen settles), `focus_window`, `list_windows`, `zoom`
  18. (full-resolution crop for small text), `cursor_position`, `open_application`, `list_applications`,
  19. `system_info`.
  20. - **Smart waiting**: after each action it waits for the UI to *react*, then for a short quiet period, so it
  21. doesn't return mid-animation or before a click has had any effect, and it gives up quickly when nothing changes.
  22. - **Won't click into the wrong window**: the Claude app pops to the front whenever you send it a message.
  23. On X11 the server checks which window is really on top at the target point, and refuses to click there
  24. or type into it if that window is protected (the Claude app, by default). Instead it tells the model to
  25. `focus_window` the right app first.
  26. - **HiDPI-aware**: screenshots are scaled down (default max 1280×800) and coordinates are mapped back to real pixels.
  27. - **Safety built in**: a kill switch command, a failsafe corner (X11), an action log and a dry-run mode. Details below.
  28. ## How it works
  29. | Session | Screenshots | Mouse & keyboard |
  30. |---|---|---|
  31. | X11 (any desktop) | `mss` (bundled), falls back to ImageMagick `import` / `scrot` | XTEST via `python-xlib` (mouse) + `xdotool` (keyboard) |
  32. | Wayland, GNOME | `gnome-screenshot` → XDG Screenshot portal | `dotool` (or `ydotool`) |
  33. | Wayland, KDE Plasma | `spectacle` → portal | `dotool` (or `ydotool`) |
  34. | Wayland, wlroots (Sway, Hyprland…) | `grim` → portal | `dotool` (or `ydotool`) |
  35. Wayland doesn't let apps move the pointer directly. Instead, `dotool` creates a virtual absolute-pointer
  36. and keyboard device through `/dev/uinput`, and the compositor treats it like real hardware.
  37. That's why Wayland needs a one-time permission setup.
  38. ## Install
  39. ### 1. System packages
  40. **X11**
  41. ```bash
  42. sudo apt install xdotool # Debian / Ubuntu
  43. sudo dnf install xdotool # Fedora
  44. sudo pacman -S xdotool # Arch
  45. ```
  46. **Wayland**: install a screenshot tool for your desktop, plus `dotool`:
  47. ```bash
  48. # Ubuntu / Debian (GNOME)
  49. sudo apt install gnome-screenshot
  50. # KDE: spectacle · Sway/Hyprland: grim
  51. # Arch: sudo pacman -S grim / yay -S dotool
  52. ```
  53. `dotool` is packaged in the AUR and some other distros. If yours doesn't have it, build it from
  54. [sr.ht/~geb/dotool](https://git.sr.ht/~geb/dotool) (`./build.sh && sudo ./build.sh install`; needs Go).
  55. `ydotool` ≥ 1.0 with `ydotoold` running also works, but its pointer positioning is less precise
  56. (it moves relatively, so pointer acceleration affects it).
  57. Then allow virtual input once, and **log out and back in**:
  58. ```bash
  59. linux-computer-use-mcp setup-wayland --yes
  60. ```
  61. ### 2. The server
  62. ```bash
  63. pipx install git+https://github.com/dhakseshr/linux-computer-use-mcp
  64. # or with uv:
  65. uv tool install git+https://github.com/dhakseshr/linux-computer-use-mcp
  66. ```
  67. ### 3. Check it
  68. ```bash
  69. linux-computer-use-mcp doctor
  70. ```
  71. ## Connect it to Claude
  72. Print a ready-made config for your machine:
  73. ```bash
  74. linux-computer-use-mcp config
  75. ```
  76. **Claude desktop app (Linux)**: add this to `~/.config/Claude/claude_desktop_config.json`, then restart the app:
  77. ```json
  78. {
  79. "mcpServers": {
  80. "linux-computer-use": {
  81. "command": "/home/you/.local/bin/linux-computer-use-mcp"
  82. }
  83. }
  84. }
  85. ```
  86. **Claude Code**
  87. ```bash
  88. claude mcp add linux-computer-use -s user -- linux-computer-use-mcp
  89. ```
  90. Then ask something like *"Open Firefox, go to the weather for Chennai and tell me tomorrow's forecast"* and watch the pointer.
  91. ## Safety
  92. This tool gives an AI real control of your mouse and keyboard. Treat it the way you would a person
  93. remote-controlling your machine.
  94. - **Kill switch**: `linux-computer-use-mcp stop` immediately blocks every action (including screenshots)
  95. until you run `linux-computer-use-mcp resume`. **Bind `stop` to a keyboard shortcut** in your desktop's
  96. settings (e.g. `Super+Escape`) so you can halt it instantly.
  97. - **Failsafe corner (X11)**: slam the mouse into the top-left corner and the next action is refused.
  98. - **Protected windows (X11)**: clicks, drags and scrolls onto a protected window, and typing while one is
  99. focused, are refused. That stops the model from typing into Claude's own chat box. The default is the
  100. Claude app; set `LCU_PROTECT_WINDOWS` to a comma-separated list of app-class substrings, or to an empty
  101. string to turn the guard off.
  102. - **Action log** at `~/.local/state/linux-computer-use/actions.log`.
  103. - **Dry run**: set `LCU_DRY_RUN=1` to log actions without performing them.
  104. - The server instructs the model to ask before sending messages, buying, deleting or changing settings,
  105. and to treat on-screen text as information, not instructions. That reduces risk but doesn't remove it.
  106. Prompt injection from web pages is a real risk, so keep an eye on what it does, and don't leave it unattended
  107. on screens that show sensitive data.
  108. ## Configuration
  109. Set these as environment variables, either in your shell or in the `"env"` block of the MCP config.
  110. | Variable | Default | Meaning |
  111. |---|---|---|
  112. | `LCU_MOVE_DURATION` | `0.12` | Seconds the pointer takes to glide to a target. `0` = jump instantly |
  113. | `LCU_AUTO_SCREENSHOT` | `1` | Actions return a screenshot once the screen settles |
  114. | `LCU_SETTLE_TIMEOUT` | `2.0` | Max seconds an action waits for the screen to stop changing |
  115. | `LCU_JPEG_QUALITY` | `75` | Screenshot JPEG quality |
  116. | `LCU_TYPE_DELAY_MS` | `12` | Delay between typed characters |
  117. | `LCU_MAX_WIDTH` / `LCU_MAX_HEIGHT` | `1280` / `800` | Max screenshot size sent to the model |
  118. | `LCU_IMAGE_FORMAT` | `jpeg` | `jpeg` (fast, small) or `png` |
  119. | `LCU_SCREENSHOT_BACKEND` | auto | `mss`, `import`, `scrot`, `grim`, `spectacle`, `gnome-screenshot`, `portal` |
  120. | `LCU_INPUT_BACKEND` | auto | `xtest`, `xdotool`, `dotool`, `ydotool` |
  121. | `LCU_SESSION` | auto | Force `x11` or `wayland` |
  122. | `LCU_FAILSAFE` | `1` | Top-left-corner failsafe (X11) |
  123. | `LCU_PROTECT_WINDOWS` | `claude` | Comma-separated app classes that must never receive clicks or keystrokes (X11). Empty = off |
  124. | `LCU_DRY_RUN` | `0` | Log actions without performing them |
  125. | `LCU_STOP_FILE` | `~/.config/linux-computer-use/STOP` | Kill-switch file |
  126. | `LCU_LOG_FILE` | `~/.local/state/linux-computer-use/actions.log` | Set empty to disable |
  127. ## Troubleshooting
  128. - **The Claude window keeps jumping in front of the app it's controlling**: on X11 the protected-window guard
  129. stops stray input, and the model can call `focus_window` to bring the target back. For the smoothest
  130. experience, snap Claude to one half of the screen (`Super+Left`) and the target app to the other half, or keep
  131. Claude on a second monitor.
  132. - **"No graphical session found"**: the MCP client launched the server without `DISPLAY`/`WAYLAND_DISPLAY`.
  133. Add them to the `"env"` block (`linux-computer-use-mcp config` prints the right values).
  134. - **GNOME asks "Allow screenshot?"**: that's the portal's one-time permission prompt. Allow it, or install `gnome-screenshot`.
  135. - **Pointer doesn't move on Wayland**: run `doctor`. Usually `/dev/uinput` isn't writable yet, because you
  136. haven't logged out since running `setup-wayland`.
  137. - **Clicks land in slightly the wrong place on Wayland with fractional scaling**: try `dotool` instead of `ydotool`,
  138. and report your setup in an issue.
  139. - **Multi-monitor**: screenshots cover all monitors as one image. Wayland absolute positioning maps across the
  140. whole layout, which works on most setups but not all.
  141. ## Limitations
  142. - On Wayland, apps can't read where the pointer is, so `cursor_position` reports the last position this server moved it to.
  143. - The X11 failsafe corner doesn't work on Wayland. Use the `stop` shortcut there.
  144. - `list_windows`, `focus_window` and the protected-window guard need X11. Wayland compositors don't let
  145. apps see other apps' windows.
  146. - While the GNOME overview (Activities) is open, the guard still sees the windows underneath it, so clicks
  147. over the Claude window's area may be refused. Use `focus_window` instead of the overview.
  148. - Flatpak or Snap sandboxed MCP clients may not be able to run the host's `xdotool`/`dotool`.
  149. ## Development
  150. ```bash
  151. git clone https://github.com/dhakseshr/linux-computer-use-mcp && cd linux-computer-use-mcp
  152. pip install -e ".[dev]"
  153. pytest # unit tests
  154. xvfb-run -s "-screen 0 1920x1080x24" pytest # + live end-to-end tests (needs xdotool, xterm, openbox)
  155. ```
  156. Contributions are welcome, especially testing on more desktops, and backends such as the
  157. RemoteDesktop portal or KDE's fake-input protocol.
  158. ## License
  159. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.