# Omarchy computer MCP

A small desktop-control fallback for MCP clients on Omarchy/Hyprland. It provides
screenshots, window focus, mouse movement/clicks, scrolling, text input, and keyboard
shortcuts. It was built for Codex CLI and speaks standard MCP over local stdio.

**Experimental.** Tested on Hyprland **0.56.2 with Lua configuration**, a single
2560×1600 display at **1.6 scale**, GTK3/native Wayland and Tk/XWayland. Other
compositor versions, layouts, applications, and multi-monitor configurations
have not been validated. This is not OpenAI's built-in Computer Use.

## Prefer an existing solution when it fits

- [linux-desktop-mcp](https://github.com/lotnikov/linux-desktop-mcp) can read and
  change accessible controls by name without borrowing the mouse or keyboard.
  Prefer it for apps with an AT-SPI tree.
- [hypruse](https://github.com/IlyasKhallouki/hypruse) has a much broader Hyprland
  interface, native Wayland pointer support, zoom, accessibility discovery, and
  action sequencing.
- [Hyprland Computer Use](https://github.com/SamSaffron/hyprland-computer-use)
  implements approved-window access with a compositor plugin.

This bridge remains useful when global input must work across native Wayland
and XWayland applications. Local testing found keyboard and XWayland failures
in the evaluated alternatives. See [the comparison and actual test results](docs/alternatives.md),
including limitations of this project. Those findings are not a claim that this
is the best general Linux automation tool.

## Install

Requirements: a running Hyprland Lua session, `hyprctl`, `grim`, `wtype`,
`xdotool`, Python 3.11+, and permission to write `/dev/uinput`. The Python
`evdev` dependency may require a compiler and Linux/Python headers when no wheel
is available. Omarchy normally already provides several of these components.

```sh
uv tool install 'git+https://github.com/Marlos001/omarchy-computer-mcp@v0.1.0'
codex mcp add omarchy-computer -- "$(command -v omarchy-computer-mcp)"
```

Restart Codex CLI and ask:

> Use omarchy-computer to inspect my desktop and interact with the test editor.

If `/dev/uinput` is not writable, mouse clicks, scrolling, and physical shortcuts
will fail. Arrange input-device access through your distribution's normal setup;
do not run the MCP server as root. This project installs no udev rules, system
service, compositor plugin, or network listener.

For another MCP client, configure `omarchy-computer-mcp` as a stdio command using
its absolute installed path. The server discovers the current user session.
With multiple Hyprland sessions, launch the client inside the intended session.

## Tools

| Tool | Purpose |
| --- | --- |
| `desktop_state` | Monitor geometry, window addresses, and active window |
| `desktop_screenshot` | One monitor at logical pixel scale |
| `desktop_focus` | Focus a known window address |
| `desktop_move` | Move in global logical coordinates |
| `desktop_click` | Left/right/middle click or double-click within the target window |
| `desktop_type` | Up to 500 Unicode characters, without replacing the clipboard |
| `desktop_key` | Physical keyboard key with optional modifiers |
| `desktop_scroll` | Scroll within the target window |

Inspect the screenshot before clicking. Screenshot pixel coordinates are relative
to the selected monitor; add the monitor's `x` and `y` origin from `desktop_state`.
Window addresses are session-local, so obtain them again after a window reopens.

Native Wayland text uses `wtype`. XWayland text uses targeted `xdotool` events.
Keyboard shortcuts and buttons use temporary virtual input devices. A small
relative-pointer motion after a compositor warp refreshes XWayland pointer focus;
this can introduce a few pixels of rounding drift. Verify small targets visually.

## Limits and control

This operates your **live desktop**. It is not a sandbox or a window-isolation
boundary. Focus checks reduce mistakes but cannot eliminate a focus race.
An overlay or popup may intercept input even when the target window is active.
Do not type or move the mouse concurrently with an automation task.

The MCP host controls tool approval. Interrupt the task in the host to stop new
calls; an already running call can finish. Virtual devices disappear when the
server exits. Screenshots return to the MCP client and are not written to disk
by the server. Application titles and captured pixels may contain private data.

Some X11 applications reject synthetic events. IMEs, password fields, protected
surfaces, games, drag-and-drop, and arbitrary application compatibility are not
validated. Prefer structured app APIs and AT-SPI controls where available.

## Development and verification

```sh
uv sync --group dev
uv run pytest
uv run ruff check .
```

Live smoke tests open a disposable test window, verify actual received events,
and restore the previous focus/pointer. Run them inside Hyprland, with the desktop
idle. The system Python must have Tkinter for XWayland, and PyGObject/GTK3 for the
native Wayland test.

```sh
uv run python tests/smoke_desktop.py
uv run python tests/smoke_desktop.py --native
```

Headless unit tests do not prove desktop compatibility. The GitHub workflow runs
only the unit, syntax, and package-build checks.

## Remove

```sh
codex mcp remove omarchy-computer
uv tool uninstall omarchy-computer-mcp
```

MIT licensed.