Claude Linux

A Claude Desktop extension that gives Claude full desktop control on Linux/X11: screenshot, mouse, keyboard, window management, clipboard, and app launch.

Fills the same niche as Windows-MCP but for Linux. Built to pair with claude-terminal-mcp — Terminal handles the shell; this handles the GUI.

---

⚠️ Security — read this first

Installing this extension gives Claude full control over your desktop. Anything you can do with a keyboard and mouse, Claude can do through this tool:

• Move your mouse anywhere and click anything (including dialogs, "Yes" buttons, Send buttons in open chat windows)
• Type into whatever window currently has focus (including password fields)
• Read and write your clipboard (so anything you've copied recently is visible)
• Launch applications
• Close windows (including unsaved work)

Treat installing this like giving someone physical access to your keyboard and mouse while they sit at your desk. Don't install it on machines with sensitive data you wouldn't want Claude to interact with, on shared systems, or if you're going to leave a chat unattended.

The denylist-style protection used by claude-terminal-mcp doesn't really apply here — a mouse click is a mouse click; you can't pattern-match intent. The safety rails in v0.1 are: (1) honest framing in this README, (2) destructiveHint: true annotations on every tool that changes system state, so Claude's own reasoning layer is aware, (3) the install flow requires explicit Extension Developer mode (red "unverified" warning).

---

What it does

Fourteen tools:

Tool	Purpose
screenshot	Capture full screen (or active window if active_window: true) as PNG. Returns path.
list_windows	Enumerate visible windows with id/pid/geometry/title.
focus_window(title_pattern)	Bring a window to the foreground.
move_window(title_pattern, x?, y?, width?, height?)	Move/resize a window.
close_window(title_pattern)	Request a window to close gracefully.
mouse_move(x, y)	Move pointer to absolute screen coordinates.
mouse_click(button?, x?, y?)	Click left/middle/right; optional coords.
mouse_drag(x1, y1, x2, y2, button?)	Drag from → to.
mouse_scroll(direction, amount?)	Scroll up/down/left/right by N clicks.
type_text(text, delay?)	Type a string into the focused window.
key_press(combo)	Press a combo like ctrl+c, alt+Tab, super, Return.
clipboard_get()	Read the CLIPBOARD selection as text.
clipboard_set(text)	Write a string to the CLIPBOARD.
launch_app(command)	Spawn an application detached (e.g. firefox, gnome-terminal, code /path).

All shell out to small, well-known X11 CLI tools — no npm dependencies.

---

Requirements

Display server: X11. Wayland is not supported in v0.1 because Wayland's security model deliberately blocks cross-process input injection. To check which session you're on:

echo $XDG_SESSION_TYPE

If it says wayland, log out and pick "Ubuntu on Xorg" (or your distro's equivalent) at the login screen.

System tools (one-time install):

sudo apt install xdotool wmctrl xclip

gnome-screenshot ships with Ubuntu GNOME; if you're on a different DE, install a screenshot tool:

# One of:
sudo apt install gnome-screenshot    # GNOME, works everywhere
sudo apt install scrot               # Minimal CLI
sudo apt install maim                # Modern replacement for scrot

OCR (optional, for screenshot_text — added in v0.2):

sudo apt install tesseract-ocr tesseract-ocr-eng
# Add tesseract-ocr-<lang> for other languages (fra, deu, nld, …).

If tesseract isn't installed, only screenshot_text is unavailable — the other 14 tools work normally.

Claude Desktop: ≥ 0.10.0 on Linux (bundles a recent Node; no system Node required).

---

Install

1. Download LinuxDesktop.mcpb from the latest release.
2. Claude Desktop → Settings → Extensions → Extension Developer section → Install Extension → select the .mcpb file.
3. Review the red "developer info not verified by Anthropic" warning. If you trust the source, click Install.
4. Back on All extensions, make sure Linux Desktop is toggled on.
5. In a chat, open the connector/tools picker and enable Linux Desktop for that conversation.

On first tool call, the server detects missing X11 utilities and returns a clear "install with: sudo apt install …" error — you don't have to read the full README to discover what's missing.

---

Usage examples

Try asking Claude:

• "Take a screenshot and tell me what's on my screen."
• "List my open windows."
• "Focus the Firefox window."
• "Open gnome-terminal and then type nvtop into it."
• "Copy 'hello world' to my clipboard."
• "Drag the Claude Desktop window to the top-left corner of the screen, resize it to 800×600."
• "Scroll down three times in the active window."

---

Known limitations (v0.1)

• X11 only. Wayland requires a totally different approach (ydotool + privileged daemon, portal APIs for screenshots). Adding Wayland support is on the roadmap but nontrivial.
• No AT-SPI UI inspection. v0.1 works with coordinates + window titles. Semantic ("click the Send button") targeting requires AT-SPI inspection, which is messy on Electron/Chromium apps and deserves its own focused v0.2.
• No OCR. Screenshots are PNGs; Claude reads them with its vision. That works well for most use cases but has no built-in "find the word 'Cancel' on screen and click it" primitive.
• Yellow "Tool result could not be submitted" banner. Cosmetic; fires on dynamic-tool-loading steps. Affects the stock Filesystem extension too. Not this extension's bug.

---

Privacy policy

No data leaves your machine. This extension runs entirely locally:

• Data collection: None. The extension does not phone home, emit telemetry, or make any network requests of its own.
• Data usage & storage: Screenshots are saved to /tmp/claude-linux-mcp/shots/ so Claude can reference them later in the same conversation. Nothing else is persisted by the extension itself.
• Clipboard: clipboard_get() reads whatever is currently on your X11 CLIPBOARD selection and passes it back to Claude Desktop in the tool result. Treat this the same way you'd treat pasting into a chat — don't ask for it if sensitive data is on your clipboard.
• Third-party sharing: None. Nothing is transmitted to Anthropic, the extension author, or any third party by this extension. (Claude Desktop itself separately sends tool inputs/outputs to Anthropic as part of the normal chat flow — that's Anthropic's relationship with you, not this extension's.)
• Retention: /tmp/claude-linux-mcp/ is cleared at every reboot. To clear manually: rm -rf /tmp/claude-linux-mcp.
• Permissions scope: All tools run with your own user's permissions — the same as anything you'd type into a terminal or do with a mouse.
• Contact / questions: Open an issue at https://github.com/LukeLamb/claude-linux-mcp/issues.

License

MIT. Use freely, attribution appreciated, no warranty.