Find and run Omarchy commands through a local MCP client.
Good to know
Commands needing sudo are always refused; guarded and unclassified groups require approval unless allowed by rules.
Unclaimed
Are you @bruce-forte?Claim this page to keep it up to date
This page was written by 
Are you @bruce-forte?Claim this page to keep it up to date
Let local AI clients inspect and control your Omarchy desktop while you manage approvals and review their activity.
What you can do with MCP Server for Omarchy
Inspect and call the live shell's bar, notification, media and loaded-plugin controls.
Good to know
Requires the running omarchy-shell; the server's own IPC target exposes only status and recent activity to agents.
Inspect monitors, workspaces, open windows and the focused window.
Good to know
Reports the current Hyprland session.
Capture a screen, window, monitor or region as an image for a local AI client.
Good to know
Images are scaled down; captures are not saved to disk and do not change the clipboard.
Extract text from a screen, window, monitor or region with OCR.
Good to know
Requires working Omarchy OCR support and the requested language.
Read and replace the desktop's text clipboard through an MCP client.
Good to know
Writing replaces the previous clipboard contents; an empty clipboard reads as an empty string. Reads exceeding 4 MiB fail with an error.
List and apply installed themes or change the desktop wallpaper.
1 other tool for switch themeGood to know
Theme names and wallpaper paths are checked before execution; a missing theme name opens a picker only in clients supporting elicitation.
Adjust volume, mute output or microphone, switch audio outputs and control media playback.
4 other tools for switch audio outputGood to know
Media commands act on the player the running shell considers active.
Show all 16
Change display brightness or keyboard backlight and toggle desktop features such as night light and do-not-disturb.
2 other tools for night lightGood to know
Feature toggles cover the bar, do-not-disturb, idle, night light, screensaver, touchpad and touchscreen.
Open a browser URL, editor path, terminal or web app through an MCP client.
Good to know
Launches return immediately without waiting for the window to close.
Show desktop notifications or temporary on-screen messages and progress indicators.
Good to know
On-screen displays fade without leaving a notification-history entry.
Read CPU, memory, battery, network and current desktop settings in one request.
Good to know
Fields are null when the machine has no corresponding component, such as a battery.
Approve or deny guarded desktop actions and save permission rules for later calls.
Good to know
Deny rules take precedence over ask and allow; sudo stays blocked, silence denies, and repeated prompts are rate-limited.
Inspect ineffective permission rules, revoke saved grants and review newly covered commands after Omarchy updates.
Good to know
New commands covered by existing allow rules remain at ask until review; the panel removes or prunes only daemon-written local grants.
Review an agent's desktop actions from the bar panel or a persistent activity log.
Good to know
Command output is never logged; arguments are logged with truncation. The default log rotates at 1 MiB and retains one previous generation.
Stop, start or restart the server and reload configuration from its keyboard-accessible bar panel.
Good to know
Port and activity-log changes require restart; other settings reload within about two seconds. A manual stop persists across logout.
Before you upgrade MCP Server for Omarchy
Newest firstSince `v1.1.0`, install affected helpers with the system package manager: executable lookup accepts only root-owned files and directory chains in `$OMARCHY_PATH/bin`, `/usr/local/bin` and `/usr/bin`.
Since `v1.2.0`, helpers inherit only allowlisted desktop and locale variables; unlisted variables such as `http_proxy` are dropped, so environment-dependent commands may stop working.
Since `v1.3.0`, output beyond `32 × max_output_b` per stream (minimum 1 MiB; default 8 MiB) terminates the command's process group. Returned output retains its head and tail and is marked truncated.
In `v1.3.0`, clipboard reads exceeding the 4 MiB helper-output ceiling fail with an error instead of buffering all text; this limit is inferred from the read path.
MCP Server for Omarchy release history 1
Control your Omarchy desktop from a local MCP client with approval rules you can inspect and change.
Details
The first release exposes command discovery and execution, shell IPC, desktop inspection and a bar panel for approvals, rules and activity. Versions 1.1.0–1.3.0 restrict runnable helpers and inherited variables and terminate commands that exceed the output ceiling.
Also: Inspect screens and windows, use the clipboard, change desktop settings and review activity; later tags restrict executable lookup, inherited variables and excessive output.
Install the Omarchy plugin from this repository; this publish covers v1.0.0–v1.3.0. Requires Omarchy 4+, Python 3.11+, first-run network access and a local HTTP MCP client configured with the generated bearer token.
Added: Find and run Omarchy commands through a local MCP c…Added: Inspect and call the live shell's bar, notification…Added: Inspect monitors, workspaces, open windows and the…Added: Capture a screen, window, monitor or region as an i…Added: Extract text from a screen, window, monitor or regi…Added: Read and replace the desktop's text clipboard throu…Added: List and apply installed themes or change the deskt…Added: Adjust volume, mute output or microphone, switch au…Added: Change display brightness or keyboard backlight and…Added: Open a browser URL, editor path, terminal or web ap…Added: Show desktop notifications or temporary on-screen m…Added: Read CPU, memory, battery, network and current desk…Added: Approve or deny guarded desktop actions and save pe…Added: Inspect ineffective permission rules, revoke saved…Added: Review an agent's desktop actions from the bar pane…Added: Stop, start or restart the server and reload config…Action requiredBehavior changedBehavior changedBehavior changed / inferred: Read and replace the desktop's text clipboard throu…
Seeded by @iluxav with Codex
Read the evidence
- bruce-forte/omarchy-mcp-server/blob/v1.0.0/README.md
- bruce-forte/omarchy-mcp-server/blob/v1.0.0/TOOLS.md
- bruce-forte/omarchy-mcp-server/blob/v1.1.0/README.md
- bruce-forte/omarchy-mcp-server/blob/v1.1.0/SECURITY.md
- bruce-forte/omarchy-mcp-server/blob/v1.2.0/SECURITY.md
- bruce-forte/omarchy-mcp-server/blob/v1.2.0/src/omarchy_mcp/trust.py
- bruce-forte/omarchy-mcp-server/blob/v1.3.0/SECURITY.md
- bruce-forte/omarchy-mcp-server/blob/v1.3.0/src/omarchy_mcp/execute.py
- bruce-forte/omarchy-mcp-server/blob/v1.3.0/src/omarchy_mcp/desktop.py