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 can read and change accessible controls by name without borrowing the mouse or keyboard. Prefer it for apps with an AT-SPI tree.

• hypruse has a much broader Hyprland interface, native Wayland pointer support, zoom, accessibility discovery, and action sequencing.

• 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, including limitations of this project. Those findings are not a claim that this is the best general Linux automation tool.

Related MCP server: pov

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.

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

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

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.

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

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

MIT licensed.