Umbriel

umbriel-mcp

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

Umbriel Wayland コンポジター用の MCP サーバーです。

MCP クライアントから Umbriel を利用できます。ウィンドウ、ワークスペース、出力の一覧表示と制御、ポインターとキーボードの操作、オプションの OCR を使った画面キャプチャ、クリップボードの読み取りと書き込みが可能です。

コンポジターの状態取得と操作は、CLI を呼び出すのではなく Umbriel の IPC ソケットに直接アクセスするため、確認に必要な往復は 1 回で済み、プロセスも起動しません。ポインター、キーボード、クリップボードには Wayland プロトコルを直接使用します。外部プログラムを呼び出すのは画面キャプチャと OCR のみです。

インストール前にお読みください

フルアクセスは、デスクトップを完全に制御できることを意味します。 デフォルトの full プロファイルでは、このサーバーに接続したエージェントが任意のコマンドを起動し、どこでも入力やクリックを行い、クリップボードを読み取って上書きし、画面を見ることができます。画面上の内容やクリップボードの内容はモデルに表示されます。より制限したい場合はプロファイルを使用してください。

これは、活発に進化しているコンポジターを追跡する、ベストエフォートの個人プロジェクトです。0.x の動作変更があり、Umbriel の変更に伴って動作しなくなる可能性があります。私が余暇に対応できる範囲を超えるサポートはお約束できません。

互換性

サポート対象は Umbriel 自体の利用可能状況に準じます。お使いのシステムで Umbriel が動作するなら、このサーバーも動作するはずです。サーバー自体は、ランタイムライブラリを必要としない x86_64 および aarch64 Linux 用の静的バイナリです。そのため、ディストリビューションが関係するのは Umbriel と 2 つの画面補助ツールのインストールのみです。

ディストリビューション	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

Umbriel がパッケージ化されていないため、古い Ubuntu リリースはサポート対象外です。

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 をインストールし、 続いてパッケージマネージャーから 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 を使えます。
• リリースには署名があります。update とインストールスクリプトは、umbriel-mcp リリースキーによる有効な署名が SHA256SUMS に付いている場合にのみリリースを受け入れます。このキーの公開鍵はバイナリとスクリプトに組み込まれており、署名を確認した後にのみチェックサムを信頼します。改ざんされたリリースや署名のないリリースは拒否されます。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 update によってインストールされた場合は、umbriel-mcp プログラム自体も削除します。シンボリックリンク経由で実行している場合は、リンクのみを削除します。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	何もしません。この操作用の CLI がないため、貼り付ける設定が表示されます

opencode または Cursor の CLI がインストールされていない場合や、Cursor の CLI に mcp add がない場合は、貼り付ける設定が代わりに表示されます。登録にプロファイルが追加されるのは --profile を渡した場合のみで、デフォルトは full のままです。

pi の登録では直接公開を使用するため、モデルのツール一覧にツールが表示されます。そのため、「ワークスペース 4 には何がありますか？」という質問には、ツールを検索したり hyprctl を試したりせず、list_windows を 1 回呼び出して回答します。以前に 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 はサーバーによるプログラムの起動を停止しますが、サンドボックスではありません。フォーカスされたターミナルに入力できるエージェントは、入力ツールを使って引き続きコマンドを実行できます。

ツール

状態の確認 — 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。これらは実際のマウスとキーボードを操作するため、デスクトップを同時に使うと操作がぶつかります。サーバーは、操作を引き継ぐ前に確認するようエージェントに指示します。入力が意図した場所に届くようにするには、次の点に注意してください。

• 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 などの設定を1つ変更し、set_keybind と remove_keybind はキー割り当てを変更します。キーと値は Umbriel のスキーマ（型、範囲、許可される値）に照らしてチェックされ、編集後の設定は umbriel config validate で検証されます。window_rule などのルールリストは、ルールを JSON 形式で受け取り、read_config に表示される順序で1から数えた位置を指定する add_rule、replace_rule、remove_rule で編集します。

変更を書き込む前に、必ず承認が必要です。

• MCP のエリシテーションに対応するクライアント（Claude Code 2.1.76+、VS Code、Cursor、opencode v2）では、バックアップを保持するチェックボックス付きで、変更内容が正確に表示されたダイアログが表示されます。書き込みを行うのは、あなたが承認した場合のみです。モデルがダイアログに回答することはできません。10分以内に回答がない場合、何も書き込まれません。
• 対応していないクライアント（pi、opencode 1.x）では、ツールは何も書き込まず、変更内容と1回限りの確認コードを返します。モデルには、変更内容を表示してバックアップを保持するか尋ね、あなたの回答を待ってから apply_config_change を呼び出すよう指示されます。この方法はモデルが指示に従うことに依存するため、ダイアログよりも安全性が劣ります。すべての書き込みツールには破壊的操作のマークが付いているため、ハーネスの権限確認プロンプトや拡張機能からも確認を求められる場合があります。
• 確認コードは10分で期限切れになり、1回のみ使用できます。また、プレビュー後にファイルが変更されている場合は拒否されます。

同じ承認手順で、以前の設定のバックアップを保持するかどうかも尋ねられます。「はい」と答えた場合、またはその質問に回答しなかった場合、バックアップは設定ファイルと同じ場所に 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 は、1台のモニター、または画面上に表示されている1つのウィンドウの画面領域を、~/Videos/umbriel-mcp/recording-<UTC time>.mp4（または XDG_VIDEOS_DIR）に録画します。指定がない限り、音声はオフです。録画はデフォルトで30秒後に自動停止します（1秒から60分まで指定可能）。stop_recording を呼び出すとそれより早く停止し、ファイルの場所を報告します。同時に実行できる録画は1つだけです。 umbriel-mcp が終了すると、録画は停止し、ファイルが完成します。録画はスクリーンショットと同様に観察のための機能であるため、すべてのプロファイルで使用できます。録画中、wf-recorder は画面上に何も表示しません。 キャプチャ対象の選択 — キャプチャ対象を指定せずにスクリーンショットや録画を依頼すると、画面全体（スクリーンショットのみ）、モニター、ウィンドウから選ぶよう求められます。録画の場合は、すでに長さを指定していない限り、30秒から60分までの長さも尋ねられます。初期設定は30秒です。ダイアログを表示するクライアントでは、選択肢が1つのダイアログにまとめて表示されます。それ以外の場合は、モデルが選択を尋ねます。モデルが自身の目的でスクリーンショットを撮ったり録画を開始したりするときは、尋ねることも、あなたの応答を待つこともありません。

画面とクリップボード — 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秒後）に待機を終了するため、スリープ時間を推測する代わりに、エージェントがページの読み込みを待てます。

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