Umbriel

umbriel-mcp

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

用于 Umbriel Wayland 合成器的 MCP 服务。

向 MCP 客户端开放 Umbriel：列出并控制窗口、工作区和输出设备，操控指针和键盘，截取屏幕并可选择进行 OCR，还能读取或写入剪贴板。

合成器状态和操作会直接通过 Umbriel 的 IPC 套接字执行，而不是调用命令行工具，因此检查只需一次往返，无需启动进程。指针、键盘和剪贴板直接使用 Wayland 协议。只有屏幕截图和 OCR 会调用外部程序。

安装前请阅读

完全访问权限意味着完全控制你的桌面。 在默认的 full 配置中，连接到此服务的 Agent 可以启动任意命令、在任何位置输入和点击、读取并覆盖剪贴板，以及查看屏幕。屏幕上或剪贴板中的所有内容对模型都可见。使用配置文件授予较少权限。

这是一个尽力维护的个人项目，跟随仍在积极演进的合成器开发。请预期 0.x 版本会有行为变更，也请预期 Umbriel 变更时项目可能会出问题。除我业余时间所能提供的支持外，不作其他支持承诺。

兼容性

支持情况取决于 Umbriel 自身的可用性：如果 Umbriel 能在你的系统上运行，此服务应该也能运行。服务本身是适用于 x86_64 和 aarch64 Linux 的静态二进制文件，无需运行时库，因此发行版只影响 Umbriel 和两个屏幕辅助工具的安装。

发行版	Umbriel	umbriel-mcp
Arch Linux	AUR umbriel-git	使用此仓库中的 makepkg（计划发布 AUR 软件包）
Ubuntu 26.04+	Noctalia APT 仓库（umbriel）	发布版二进制文件
Debian Trixie / Sid	Noctalia APT 仓库（umbriel）	发布版二进制文件
Fedora	Terra（umbriel-nightly）	发布版二进制文件
其他发行版	请参阅 Umbriel 安装页面	发布版二进制文件或 cargo install

不支持较旧版本的 Ubuntu，因为 Umbriel 没有为其打包。

Arch 用户注意： 名为 umbriel 的 AUR 软件包只是一个占位包，并非合成器。请勿安装；合成器的软件包是 umbriel-git。

安装

以下每种方式都会安装 Umbriel、屏幕辅助工具和 umbriel-mcp，然后检查安装结果。如果你已经在运行 Umbriel，可跳过 Umbriel 安装步骤。Umbriel 命令摘自其安装页面；如有变更，请查看该页面。

Arch Linux

yay -S umbriel-git                                     # the compositor, if needed
sudo pacman -S grim tesseract tesseract-data-eng wf-recorder   # screenshots, OCR, recording

然后，将此服务作为从本仓库配方构建的 pacman 软件包安装。它会下载预构建的发布版二进制文件并检查校验和，因此无需编译：

git clone https://github.com/dot-ASH/umbriel-mcp
cd umbriel-mcp/packaging/aur-bin
makepkg -si
umbriel-mcp doctor

稍后可用 sudo pacman -R umbriel-mcp-bin 卸载。计划发布同名 AUR 软件包；发布后，本节会改为使用 yay -S umbriel-mcp-bin。

Ubuntu 26.04 及更高版本

1. 如有需要，从 Noctalia APT 仓库安装 Umbriel（仅支持 amd64 和 arm64）：

   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
   

2. 安装屏幕辅助工具：

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

3. 安装服务：

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

   这会为你的架构下载最新发布版，根据该版本的 SHA256SUMS 检查文件，将其安装到 ~/.local/bin/umbriel-mcp（无需 sudo），并运行 umbriel-mcp doctor。Ubuntu 会在该目录存在后于登录时将 ~/.local/bin 添加到 PATH，因此如果之后找不到 umbriel-mcp，请注销并重新登录。如果你将较旧版本安装到了 /usr/local/bin，脚本会提示你将其移除。

   不使用脚本手动安装

   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
   

4. 在 Umbriel 会话中的终端里检查设置：

   umbriel-mcp doctor
   

Debian Trixie 和 Sid

与 Ubuntu 的步骤相同，但使用 Debian 仓库源；在 Trixie 上还需使用 backports 套件：

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

然后安装服务，该步骤也会运行 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

然后安装服务，该步骤也会运行 umbriel-mcp doctor：

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

其他发行版

按照 Umbriel 安装页面安装 Umbriel， 然后通过软件包管理器安装 grim、tesseract 和 Tesseract 的英语数据（eng.traineddata）。使用 curl -fsSL https://raw.githubusercontent.com/dot-ASH/umbriel-mcp/main/install.sh | sh 安装服务，或使用 Cargo 构建（需要 Rust 1.89 或更高版本，例如从 rustup 安装）：

cargo install umbriel-mcp --locked

umbriel-mcp doctor 会列出在 Arch、Debian/Ubuntu 和 Fedora 上需要安装的确切软件包，并在其他发行版上提供通用指导。

更新

umbriel-mcp update            # install the latest release in place
umbriel-mcp update --check    # only report whether one exists

update 会下载最新版本，根据 SHA256SUMS 校验文件，确认新二进制文件能够运行且报告的版本符合预期，然后才替换旧文件，因此更新失败不会影响旧二进制文件的正常运行。之后请重启你的运行环境；正在运行的会话会继续使用旧版本。umbriel-mcp doctor 也会提示是否有新版本。后台不会检查更新。

• 如果二进制文件位于你无权写入的目录中（例如 /usr/local/bin），它会提示你运行 sudo umbriel-mcp update。
• 如果它是通过软件包管理器（pacman 或 makepkg、cargo install、Nix）安装的，它会拒绝更新，并告知你软件包管理器对应的命令，以免两者版本不一致。
• 0.3.0 之前的版本无法自行更新到已签名版本；请运行一次安装脚本以安装 0.3.0，此后即可使用 umbriel-mcp update。
• 发布版本均已签名。只有当 SHA256SUMS 带有 umbriel-mcp 发布密钥的有效签名时，update 和安装脚本才会接受该版本。该密钥的公钥部分内置于二进制文件和脚本中；只有通过验证后才会信任其校验和。遭到篡改或未签名的发布版本会被拒绝。即使 GitHub 账户遭到入侵，更新仍受到保护；但使用脚本首次安装不受此保护，因为脚本本身来自 GitHub。
• 0.2.3 及更早版本的发布未经签名，因此脚本和 update 只会安装 0.3.0 及更高版本。

卸载

umbriel-mcp uninstall

此操作会列出将要删除的内容，并询问一次（--yes 可跳过询问）：

• 在 pi、Claude Code、opencode、Cursor、VS Code 或 Zed 中注册的 umbriel 服务。 Claude Code 会通过其自身的 CLI 取消注册；对于其他工具，只会从配置文件中删除 umbriel 条目，注释、格式和其他服务均保持不变。如果名为 umbriel 的条目运行的是其他程序，则会保留。
• umbriel-mcp 程序本身（如果它是通过安装脚本或 umbriel-mcp update 安装的）。如果你通过符号链接运行它，只会删除链接。如果它是通过 pacman、cargo 或 Nix 安装的，则会打印相应的卸载命令。

--keep-binary 只会取消注册。配置备份和屏幕录制会列出，但不会删除。之后请重启任何正在运行的运行环境。不会搜索单个项目中的注册项（项目的 opencode.json 或 .cursor/mcp.json）；请手动删除这些条目。

要求

指针、键盘和剪贴板功能只需 Umbriel 会话正在运行，无需其他依赖。屏幕工具才需要以下外部程序：

工具	用途	Arch	Debian/Ubuntu	Fedora
grim	screenshot、OCR 工具	grim	grim	grim
tesseract	screenshot_with_ocr、find_text_on_screen、click_text	tesseract	tesseract-ocr	tesseract
英语 OCR 数据	同上	tesseract-data-eng	tesseract-ocr-eng	tesseract-langpack-eng
wf-recorder	start_recording、stop_recording	wf-recorder	wf-recorder	wf-recorder

这些工具始终会显示；如果调用所需的程序缺失，则会报错并指出要安装的软件包。

套接字通过 UMBRIEL_SOCKET 查找；如果未设置，则回退到 $XDG_RUNTIME_DIR/umbriel-$WAYLAND_DISPLAY.sock。

在你的执行环境中注册

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

这会通过各执行环境自己的 CLI 注册服务，因此 umbriel-mcp 不会自行读取或编辑它们的配置文件：

执行环境	执行命令
pi	使用直接暴露和描述运行 pi mcp add
Claude Code	claude mcp add --scope user
VS Code	code --add-mcp
opencode	opencode mcp add
Cursor	如果你的 cursor-agent 支持，则运行 cursor-agent mcp add
Zed	无需执行：Zed 没有用于此操作的 CLI，因此会打印供粘贴的配置

如果未安装 opencode 或 Cursor 的 CLI，或者 Cursor 的 CLI 不支持 mcp add，则会打印供粘贴的配置。只有传入 --profile 时，注册时才会添加配置；因此默认配置仍为 full。

pi 注册使用直接暴露，因此模型会在工具列表中看到这些工具，并通过一次 list_windows 调用回答“工作区 4 上有什么？”，而不是搜索工具或尝试运行 hyprctl。如果你之前手动注册了 pi，请再次运行 umbriel-mcp install pi，以切换为直接暴露。Zed 代码片段保留 "args": []，因为如果缺少该项，Zed 会拒绝整个设置文件。

任何其他 MCP 客户端都可以使用纯 stdio 形式：

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

检查设置

umbriel-mcp doctor 会验证 Umbriel 套接字是否可访问，合成器是否提供虚拟指针和虚拟键盘协议，以及是否已安装 grim、tesseract、Tesseract 的英语数据和 wf-recorder。每个问题都会单独列出，并附上在 Arch、Debian/Ubuntu 和 Fedora 上修复问题的命令；其他发行版则会提供通用建议。只有在所有条件都满足时，它才会以状态码 0 退出。

配置档案

--profile 会限制服务可以执行的操作。每个配置档案中都会显示所有工具；不允许执行的调用会返回错误，并指出配置档案名称。

配置档案	允许的操作
full（默认）	所有操作，包括 launch_app 和启动操作
no-exec	除启动程序之外的所有操作：拒绝 launch_app 和任何会启动程序的 run_action
read-only	查询、屏幕截图、OCR 和读取剪贴板

no-exec 会阻止服务启动程序，但它不是沙箱。能够向已聚焦终端输入内容的 Agent 仍可通过输入工具运行命令。

工具

检查 — list_windows、list_workspaces、list_outputs、get_active_window、list_layers。窗口和显示器列表默认简洁显示：窗口包含 id、应用、标题、位置、尺寸、工作区和 has_keyboard_focus；显示器包含名称、位置、尺寸、当前模式、缩放比例和工作区。传入 detail: true 可查看 Umbriel 报告的所有字段，包括每种显示模式。

窗口和工作区控制 — switch_workspace、focus_window、close_window、kill_window、move_window_to_workspace、toggle_fullscreen、toggle_floating、resize_window、set_workspace_layout、toggle_overview、launch_app、run_action

输入 — mouse_move、mouse_click、mouse_scroll、mouse_drag、type_text、key_press。这些工具会操作你的实际鼠标和键盘，因此如果你同时使用桌面，操作会相互冲突；服务会提示 Agent 在接管前先询问。为确保输入发送到预期位置：

• type_text 和 key_press 接受 window_id：如果该窗口未获得键盘焦点，就不会输入任何内容，错误信息会指出当前获得焦点的窗口。
• mouse_click 和 mouse_move 接受 window_id，以及以该窗口左上角为原点计算的 x 和 y。如果窗口不在屏幕上，或坐标点位于窗口之外，操作会被拒绝。
• 输入、按键或点击后，结果会说明哪个窗口获得了键盘焦点。 关于 Umbriel 本身 — umbriel_info（版本、键盘布局、子地图、颜色和撕裂状态）、list_actions（run_action 和按键绑定接受的所有操作，可筛选）、config_options（来自 Umbriel 自身架构的准确配置键、类型、默认值和允许值）、read_config（读取你的配置或其中一个部分，例如 keybinds，并进行验证）。这些工具会读取已安装的 umbriel 命令和你的配置，因此与正在运行的版本一致。架构不包含文字说明；相关解释请参阅 Umbriel 文档。

更改设置 — set_option 和 reset_option 用于更改单项设置，例如 layout.gap 或 appearance.blur.enabled；set_keybind 和 remove_keybind 用于更改按键绑定。系统会根据 Umbriel 的架构检查键和值（类型、范围、允许值），然后使用 umbriel config validate 检查编辑后的配置。对于 window_rule 等规则列表，可使用 add_rule、replace_rule 和 remove_rule 进行编辑；这些工具接受 JSON 格式的规则，以及按 read_config 显示顺序从 1 开始计数的位置。

每项更改都必须先经你批准，之后才会写入：

• 在支持 MCP elicitation 的客户端（Claude Code 2.1.76+、VS Code、Cursor、opencode v2）中，你会看到一个显示确切更改内容的对话框，并可勾选是否保留备份。只有你批准后才会写入；模型无法回答此对话框。10 分钟内未作答则不会写入任何内容。
• 在不支持该功能的客户端（pi、opencode 1.x）中，工具不会写入任何内容，而是返回更改内容和一次性确认码。模型会被告知向你展示更改内容、询问是否保留备份，并等待你的答复后再调用 apply_config_change。这依赖模型遵循该指示，因此安全性不如对话框。所有写入工具都标记为有破坏性，因此运行环境的权限提示或扩展也可以向你确认。
• 确认码会在 10 分钟后过期，只能使用一次；如果预览后文件发生变化，确认码将被拒绝。

相同的审批步骤也会询问你是否要保留上一版配置的备份。如果你回答“是”，或没有回答此问题，备份会保存到配置文件旁边，命名为 config.toml.bak-<time>；回答“否”可避免产生备份文件。每当写入新备份时，umbriel-mcp 会保留自身最新的 5 个备份，并删除更早的备份；启动时使用 --keep-backups N 可保留更多备份（最多 1000 个）。写入更改时，仅会修改发生变化的行（保留注释和格式）；符号链接配置仍会保持为符号链接，Umbriel 会立即应用更改。

配置文件仍受配置档案限制。read-only 会拒绝所有更改。no-exec 会拒绝 spawn: 按键绑定和热角操作，以及可能启动程序、加载文件或削弱安全检查的设置（general.autostart、events、environment、include、效果着色器、drm、screencast.disable_dynamic_confirmation）；这些操作需要 full。始终会拒绝禁用唯一已启用输出设备的操作；更改键盘布局或 general.mod_key 时会显示警告。

录制 — start_recording 会录制一台显示器，或录制一个位于屏幕上的窗口区域，并将文件保存到 ~/Videos/umbriel-mcp/recording-<UTC time>.mp4（或你的 XDG_VIDEOS_DIR）。除非明确请求，否则不会录制音频。录制默认在 30 秒后自动停止（允许设置为 1 秒至 60 分钟）；stop_recording 可提前停止录制并报告文件位置，同一时间只能进行一次录制。 如果 umbriel-mcp 退出，录制会停止并完成文件写入。录制与屏幕截图一样属于观察操作，因此所有配置档案都允许录制。wf-recorder 录制时屏幕上不会显示任何内容。 选择捕获内容 — 如果你请求截图或录制，却没有说明要捕获什么，系统会让你选择：整个屏幕（仅限截图）、某台显示器或某个窗口。录制时，系统还会询问时长，可选范围为 30 秒到 60 分钟，默认预选 30 秒；除非你已说明时长。带有对话框的客户端会在一个对话框中显示这些选项；其他客户端则由模型询问你。模型出于自身需要截取屏幕或开始录制时，不会询问，也不会等待你。

屏幕与剪贴板 — screenshot、screenshot_with_ocr、find_text_on_screen、click_text、wait_for_text、wait_for_change、clipboard_read、clipboard_write。

• 使用 window_id 时，捕获和文本搜索仅涵盖该窗口，即使它位于隐藏工作区也一样，且不会切换到该窗口（需要 grim 1.5 或更高版本；较旧的 grim 只能捕获屏幕上可见的窗口）。这样就不会捕获其他窗口。
• 使用 region（屏幕坐标中的 x、y、width、height）时，只会捕获该矩形区域，并保持完整分辨率，方便放大查看细节。
• 每次捕获都会注明时间；如果窗口标题自上次捕获后发生了变化，也会予以提示，这通常意味着窗口显示了不同的页面，或有其他人在使用它。
• wait_for_text 会等待文本出现。wait_for_change 会等待窗口、显示器或区域与上次捕获相比发生变化，并在其停止变化后返回稳定的画面；如果没有变化，也会说明这一点。两者默认最多等待 10 秒（最长 30 秒），因此 Agent 可以等待页面加载，而不必靠猜测来设置休眠时间。

key_press 接受诸如 ctrl+shift+Tab、super+q、F5 或 alt+Left 这样的组合键；大写字母（ctrl+A）表示同时按下 Shift。type_text 接受任意 Unicode 文本，其中 \n 会作为 Return 键输入，\t 会作为 Tab 键输入。

run_action 接受 umbriel msg --help 中的任意操作，因此即使没有专用工具，也能使用合成器支持的全部动词。

说明

Umbriel 中的工作区隶属于某个输出设备，而非一个全局工作区池。选择器接受位置或名称，也支持可选的 /output 后缀；workspace 和 output 参数会为你构造该后缀。

默认情况下，截图会缩小到 1024px 宽，并以 JPEG 格式返回，同时附带坐标映射说明，以便从图像坐标还原屏幕坐标。OCR 则有所不同：它始终在完整分辨率的捕获图像上运行，因为在缩小后的预览图中识别文本会一无所获。因此，find_text_on_screen 和 click_text 会直接报告绝对屏幕坐标，并支持匹配 Open File 这样的多词短语。

许可证

MIT