Umbriel

umbriel-mcp

mcp-name: io.github.dot-ASH/umbriel-mcp

An MCP server for the Umbriel Wayland compositor.

Exposes Umbriel to MCP clients: list and control windows, workspaces and outputs, drive the pointer and keyboard, capture the screen with optional OCR, and read or write the clipboard.

Compositor state and actions go straight to Umbriel's IPC socket rather than shelling out to the CLI, so inspection costs one round trip and no process spawn. Pointer, keyboard, and clipboard use Wayland protocols directly. Only screen capture and OCR call external programs.

Read this before installing

Full access means full control of your desktop. In the default full profile an agent connected to this server can launch arbitrary commands, type and click anywhere, read and overwrite your clipboard, and see your screen. Anything on screen or in the clipboard is visible to the model. Use the profiles to grant less.

This is a best-effort personal project that tracks an actively evolving compositor. Expect 0.x behavior changes, and expect it to break when Umbriel changes. There is no support promise beyond what I can do in my spare time.

Compatibility

Support follows Umbriel's own availability: if Umbriel runs on your system, this server should. The server itself is a static binary for x86_64 and aarch64 Linux with no runtime libraries, so the distribution only matters for installing Umbriel and the two screen helpers.

Older Ubuntu releases are not supported because Umbriel is not packaged for them.

Warning for Arch users: the AUR package named umbriel is a placeholder and is not the compositor. Do not install it; the compositor is umbriel-git.

Install

Each path below installs Umbriel, the screen helpers, and umbriel-mcp, then checks the result. Skip the Umbriel step if you already run it. The Umbriel commands are copied from its installation page; check there if they have changed.

Arch Linux

yay -S umbriel-git                                     # the compositor, if needed

sudo pacman -S grim tesseract tesseract-data-eng wf-recorder # screenshots, OCR, recording

Then install the server as a pacman package built from this repository's recipe. It downloads the prebuilt release binary and checks its checksum, so nothing is compiled:

git clone https://github.com/dot-ASH/umbriel-mcp

cd umbriel-mcp/packaging/aur-bin makepkg -si umbriel-mcp doctor

Remove it later with sudo pacman -R umbriel-mcp-bin. An AUR package of the same name is planned; this section will switch to yay -S umbriel-mcp-bin once it is published.

Ubuntu 26.04 and newer

1. Install Umbriel from the Noctalia APT repository (amd64 and arm64 only), if needed:

   wget https://pkg.noctalia.dev/deb/nickh-archive-keyring.deb

sudo dpkg -i nickh-archive-keyring.deb sudo wget -O /etc/apt/sources.list.d/noctalia-resolute.sources \ https://pkg.noctalia.dev/deb/noctalia-resolute.sources sudo apt update sudo apt install umbriel

1. Install the screen helpers:

   sudo apt install grim tesseract-ocr tesseract-ocr-eng wf-recorder

1. Install the server:

   curl -fsSL https://raw.githubusercontent.com/dot-ASH/umbriel-mcp/main/install.sh | sh

This downloads the latest release for your architecture, checks it against the release's SHA256SUMS, installs it to ~/.local/bin/umbriel-mcp (no sudo), and runs umbriel-mcp doctor. Ubuntu adds ~/.local/bin to PATH at login once the folder exists, so log out and back in if umbriel-mcp is not found afterwards. If you installed an older version into /usr/local/bin, the script tells you to remove it.

Manual install without the script

   arch=$(uname -m)   # x86_64 or aarch64

tag=v0.4.1 base="https://github.com/dot-ASH/umbriel-mcp/releases/download/$tag" curl -LO "$base/umbriel-mcp-$tag-$arch-linux.tar.gz" curl -LO "$base/SHA256SUMS" sha256sum --check --ignore-missing SHA256SUMS tar -xzf "umbriel-mcp-$tag-$arch-linux.tar.gz" install -Dm755 "umbriel-mcp-$tag-$arch-linux/umbriel-mcp" ~/.local/bin/umbriel-mcp

1. Check the setup from a terminal inside the Umbriel session:

   umbriel-mcp doctor

Debian Trixie and Sid

Same as Ubuntu, with the Debian repository source and, on Trixie, the backports suite:

wget https://pkg.noctalia.dev/deb/nickh-archive-keyring.deb

sudo dpkg -i nickh-archive-keyring.deb sudo wget -O /etc/apt/sources.list.d/noctalia-trixie.sources \ https://pkg.noctalia.dev/deb/noctalia-trixie.sources # Sid: noctalia-unstable.sources sudo apt update sudo apt install -t trixie-backports umbriel # Sid: sudo apt install umbriel sudo apt install grim tesseract-ocr tesseract-ocr-eng wf-recorder

Then install the server, which also runs umbriel-mcp doctor:

curl -fsSL https://raw.githubusercontent.com/dot-ASH/umbriel-mcp/main/install.sh | sh

Fedora

sudo dnf install umbriel-nightly                              # from the Terra repository

sudo dnf install grim tesseract tesseract-langpack-eng wf-recorder

Then install the server, which also runs umbriel-mcp doctor:

curl -fsSL https://raw.githubusercontent.com/dot-ASH/umbriel-mcp/main/install.sh | sh

Other distributions

Install Umbriel following its installation page, then grim, tesseract, and Tesseract's English data (eng.traineddata) from your package manager. Install the server with curl -fsSL https://raw.githubusercontent.com/dot-ASH/umbriel-mcp/main/install.sh | sh, or build it with Cargo (needs Rust 1.89 or newer, for example from rustup):

cargo install umbriel-mcp --locked

umbriel-mcp doctor names the exact packages to install on Arch, Debian/Ubuntu, and Fedora, and gives generic guidance elsewhere.

Updating

umbriel-mcp update            # install the latest release in place

umbriel-mcp update --check # only report whether one exists

update downloads the latest release, checks it against SHA256SUMS, confirms the new binary runs and reports the expected version, and only then replaces the old one, so a failed update leaves the old binary working. Restart your harness afterwards; running sessions keep the old version. umbriel-mcp doctor also says when a newer version exists. Nothing checks for updates in the background.

• If the binary is in a folder you cannot write to, such as /usr/local/bin, it asks you to run sudo umbriel-mcp update.
• If it was installed by a package manager (pacman or makepkg, cargo install, Nix), it refuses and tells you the package manager's command instead, so the two never disagree.
• Versions before 0.3.0 cannot update themselves to a signed release; run the install script once to get 0.3.0, and umbriel-mcp update works from then on.
• Releases are signed. update and the install script accept a release only if its SHA256SUMS carries a valid signature from the umbriel-mcp release key, whose public half is built into the binary and the script, and only then trust its checksums. A tampered or unsigned release is refused. Updates are protected even if the GitHub account were compromised; a first install with the script is not, because the script itself comes from GitHub.
• Releases 0.2.3 and older are unsigned, so the script and update only install 0.3.0 and newer.

Uninstalling

umbriel-mcp uninstall

This lists what it will remove and asks once (--yes skips the question):

• the umbriel server registered with pi, Claude Code, opencode, Cursor, VS Code or Zed. Claude Code is unregistered through its own CLI; in the others' config files only the umbriel entry is deleted, and comments, formatting and other servers stay as they were. An entry named umbriel that runs some other program is left alone.
• the umbriel-mcp program itself, when the install script or umbriel-mcp update put it there. If you run it through a symlink, only the link is removed. For a pacman, cargo or Nix install it prints the command to run instead.

--keep-binary only unregisters. Config backups and screen recordings are listed but kept. Restart any running harness afterwards. Registrations inside a single project (a project's opencode.json or .cursor/mcp.json) are not searched; delete those entries by hand.

Requirements

Pointer, keyboard, and clipboard need nothing beyond a running Umbriel session. These external programs are needed only for the screen tools:

The tools are always listed; a call that needs a missing program fails with an error naming the package to install.

The socket is found through UMBRIEL_SOCKET, falling back to $XDG_RUNTIME_DIR/umbriel-$WAYLAND_DISPLAY.sock.

Register with your harness

umbriel-mcp install pi            # also: claude-code, vscode, opencode, cursor

umbriel-mcp install zed # prints config to paste umbriel-mcp install claude-code --profile no-exec

This registers the server through each harness's own CLI, so umbriel-mcp never reads or edits their config files itself:

If opencode's or Cursor's CLI is not installed, or Cursor's has no mcp add, the config to paste is printed instead. A profile is added to the registration only if you pass --profile, so the default stays full.

The pi registration uses direct exposure, so the model sees the tools in its tool list and answers "what's on workspace 4?" with one list_windows call instead of searching for tools or trying hyprctl. If you registered pi by hand earlier, run umbriel-mcp install pi again to switch to direct exposure. The Zed snippet keeps "args": [] because Zed rejects its whole settings file if it is missing.

Any other MCP client can use the plain stdio form:

{

"mcpServers": { "umbriel": { "command": "umbriel-mcp", "args": [] } } }

Checking your setup

umbriel-mcp doctor verifies that the Umbriel socket is reachable, that the compositor offers the virtual-pointer and virtual-keyboard protocols, and that grim, tesseract, and Tesseract's English data and wf-recorder are installed. Each problem is listed on its own with the command to fix it on Arch, Debian/Ubuntu, and Fedora, or generic advice on other distributions. It exits with status 0 only when everything is ready.

Profiles

--profile limits what the server will do. Every tool stays visible in every profile; a c