brand-mcp
Provides tools for controlling and automating the Hyprland compositor, including racing multiple focus-actuation paths, verifying window focus, dispatching pointer/keyboard/screenshot/session actions, managing stale targets, and enforcing security policies for agent control.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@brand-mcp focus the terminal window and type 'ls -la'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π brand
The Hyprland agent-control plane that refuses to lie about focus.
Why should I care? Every agent-control tool for Hyprland dispatches a focus command and trusts the
ok. On Hyprland 0.56.x the IPC Lua API silently broke (hlis booleantrueβhyprctl eval "return type(hl.dsp)"errors), so thoseoks were fiction and agents typed into the wrong window. brand races three independent actuation paths concurrently and only declares victory when the compositor itself reports the right window focused. A bareokthat didn't move focus is a loss β retried, aggregated, and reported honestly.
Rebirth of the archived Hypr-Agent-Portal β forked, re-themed, and actively maintained by toxicwind. The original author archived it believing CUA made it redundant; we disagree: nobody else verifies focus.
π― Hyper-race focus β plugin dispatcher,
wlrctl, and legacyhyprctlraced concurrently; first strictly-verified win takes it𧬠Native hyprpm plugin β dispatchers run inside the compositor, immune to the IPC-Lua breakage:
manage,pointer,keyboard,screenshot,session,panic,guard,approvalπ‘οΈ Stale-target refusal β windows are identified by
address@pid@starttime; a recycled address can never steal focusπ Honest errors β
VerificationFailed/StaleTargettaxonomy instead of silent successβ¨οΈ AT-SPI input path β accessibility-native typing, no ydotool daemon
π Security policy β capability allowlists, panic mode, privacy denylist for screenshots, human input preempts the agent instantly
π§ͺ Composable testing β
BRAND_MOCK_COMPOSITOR=1andBRAND_DRY_RUN=1let you develop the whole stack with no compositor at all
Diagram
flowchart LR
A[MCP client] --> B[brand-mcp.py]
B --> C{focus_window_race}
C -->|A| D["brand:manage focus<br/>(native plugin)"]
C -->|B| E["wlrctl<br/>(external)"]
C -->|C| F["hyprctl focuswindow<br/>(legacy)"]
D --> G[Hyprland compositor]
E --> G
F --> G
G --> H{"hyprctl -j activewindow<br/>== requested address?"}
H -->|yes| I[β
verified win]
H -->|no| J[β path loses,<br/>errors aggregated]Related MCP server: cvision-mcp
Quick start
hyprpm add https://github.com/toxicwind/brand && hyprpm enable brand && hyprpm reloadpython3 mcp/brand-mcp.py # stdio MCP server β point your agent at it# hyprland.conf β capabilities are opt-in
plugin {
brand {
allow_pointer = 1
allow_keyboard = 1
allow_screenshot = 1
allow_session = 1
}
}Architecture
Layer | Lives in | Job |
MCP server |
| Tool surface: |
Hyper-race |
| Races actuation paths, strict verification only |
Window mgmt |
| Stale-target refusal, |
Native plugin |
| In-compositor dispatchers; bypasses broken IPC Lua |
Input | AT-SPI | Focused-editable text insertion, no daemon |
The key insight: the plugin never touches the IPC Lua state, so the 0.56.x
hl-boolean breakage doesn't apply to it. The Python side treats the plugin as
the preferred path but never the only path β if the plugin is absent or
disabled, the race still runs on wlrctl + legacy hyprctl, verified the same
way.
Config
Plugin block (hyprland.conf, hyprlang or Lua under plugin.brand):
Key | Default | Purpose |
| 1 | Background pointer dispatchers |
| 1 | Background keyboard dispatchers |
| 1 | Compositor screenshot dispatchers |
| 1 | Workspace session dispatchers |
| 1 / 30000 | On-screen agent-activity indicator |
| 1 | Physical input preempts the agent |
| KeePassXC,1Password | Classes hidden from screenshots |
Environment (local dev / CI β see .env.example):
Variable | Purpose |
| Skip the native plugin path; race |
| Log every actuation, change nothing |
| Talk to the in-repo mock instead of a real compositor |
Dev
# plugin
cmake -S . -B build && cmake --build build # -> build/libbrand.so
# tests β self-contained runners, no pytest needed (mock compositor, no Hyprland)
python3 tests/mcp_smoke.py mcp/brand-mcp.py
for t in tests/*.py; do
case "$t" in tests/mcp_smoke.py|tests/mock_compositor.py) continue;; esac
python3 "$t"
doneLicense + security
GPL-3.0 β see LICENSE. Fork lineage: full upstream history preserved
(upstream remote β gfhdhytghd/Hypr-Agent-Portal).
Security model: SECURITY.md. Short version β the plugin is a
deliberately narrow gateway: callers can't name arbitrary Hyprland dispatchers,
every window target is address@pid@starttime qualified, the session lock
blocks all management, and one brand:panic freezes everything.
Available Tools
45 toolsaudit_replayCDestructive
Preflight the redacted audit journal and optionally replay only entries that remain safe after identity and policy validation.
Inputs: execute, allow_clipboard, confirmation_token, max_record_age_seconds.
clickBDestructive
Click a visible element by index, accessible name/text, or screenshot/window-relative coordinates. Element clicks use the native pointer path so the visible agent cursor overlay appears.
Inputs: app (required), x, y, name, +7 more.
click_markBDestructive
Click one bound Set-of-Marks id after live identity, geometry, and screenshot-hash validation.
Inputs: app (required), mark_id (required), marks_id (required), click_count, +2 more.
click_textBDestructive
Click OCR text from an opaque current ocr_id. The server revalidates screenshot hash, process identity, and geometry before input.
Inputs: app (required), text (required), ocr_id (required), nth, +5 more.
computerbrandBDestructive
brand compatibility tool for Hyprland background Computer Use, including browser/Chromium control through Hyprland. Prefer app plus get_app_state/screenshot coordinates; target/x/y global coordinates are only the low-level fallback. Do not use Browser MCP when the user explicitly asks for brand. Do not use the obsolete hyprcum namespace.
Inputs: action (required), x, y, dx, +84 more.
double_clickCDestructive
Compatibility alias for a double left click.
Inputs: app (required), x, y, name, +5 more.
dragBDestructive
Drag from one screenshot/window-relative coordinate to another.
Inputs: app (required), to_x, to_y, from_x, +6 more.
get_app_stateARead-onlyIdempotent
Get a target app/window screenshot, accessibility tree, and uiHints. Call this before action tools, then use element_index or screenshot/window-relative coordinates. uiHints separates AT-SPI menu entries from tab/ribbon/toolbar controls; do not substitute a same-named menu for a requested tab.
Inputs: app (required).
get_cursor_positionBRead-onlyIdempotent
Return the current cursor position in monitor, screenshot, or window-relative coordinates.
Inputs: app, source, include_global.
get_marksCRead-onlyIdempotent
Render a non-destructive numbered Set-of-Marks overlay for a bound target screenshot and return an opaque marks_id mapping.
Inputs: app (required), zoom, scale, format, +7 more.
get_screenshotDRead-onlyIdempotent
Compatibility alias for screenshot.
Inputs: app, zoom, scale, format, +7 more.
hoverBDestructive
Compatibility alias: move the background pointer to an element or coordinate without clicking.
Inputs: app (required), x, y, name, +5 more.
keyADestructive
Compatibility alias for press_key. Accepts key, keys, modifiers, keycode, or text.
Inputs: app (required), key, keys, text, +4 more.
launch_appADestructive
Open or launch an app through Hyprland and return a window selector. By default this reuses an already running matching window; set reuse_existing=false only when the user explicitly asks for a new instance/window. For browser tasks, use this instead of Browser MCP only when an app launch/open is requested.
Inputs: app, url, args, command, +4 more.
left_clickBDestructive
Compatibility alias for click with the left button.
Inputs: app (required), x, y, name, +5 more.
left_click_dragCDestructive
Compatibility alias for drag using start_coordinate and coordinate.
Inputs: app (required), coordinate (required), start_coordinate (required), duration, +2 more.
list_appsARead-onlyIdempotent
List running Hyprland apps/windows available to brand. Start here before choosing a target app unless the user explicitly asks to launch a new app/window.
Inputs: no named parameters.
list_windowsARead-onlyIdempotent
Compatibility alias for list_apps.
Inputs: no named parameters.
list_workspacesBRead-onlyIdempotent
List Hyprland workspaces; special workspaces are included by default and explicitly identified by Hyprland.
Inputs: include_special.
manage_windowCDestructive
Targeted, verified Hyprland window management: focus/close/move/resize/minimize/maximize/fullscreen/floating/pin/move_to_workspace.
Inputs: action (required), x, y, app, +10 more.
manage_workspaceCDestructive
Verified Hyprland workspace switch/create-or-activate/rename and targeted window move. special: selectors retain Hyprland special-workspace semantics.
Inputs: action (required), workspace (required), app, follow, +4 more.
middle_clickBDestructive
Compatibility alias for click with the middle button.
Inputs: app (required), x, y, name, +5 more.
move_mouseCDestructive
Compatibility alias for hover.
Inputs: app (required), x, y, name, +5 more.
ocrARead-onlyIdempotent
Run a local OCR backend on a newly captured, privacy-filtered target screenshot. Returns normalized confidence 0..1, screenshot pixel boxes, and an opaque short-lived ocr_id.
Inputs: app (required), region, backend, timeout, +3 more.
open_appBDestructive
Compatibility alias for launch_app.
Inputs: app, url, args, command, +4 more.
panicADestructive
Immediately cancel active background operations. panic latches writes off; cancel is one-shot; resume clears the latch; status is read-only.
Inputs: mode, confirmation_token.
paste_textADestructive
Paste text through the clipboard into the target app. Prefer this for multiline, tabular, CSV/TSV, Unicode-heavy, or long text because it is much faster than key-by-key typing.
Inputs: app (required), text (required), restore_delay, prefer_related, +2 more.
perform_secondary_actionCDestructive
Invoke a secondary AT-SPI action exposed by an element.
Inputs: app (required), action (required), element_index (required), confirmation_token.
press_keyBDestructive
Press a key or key-combination, using xdotool-style syntax such as ctrl+v, Return, alt+left, or super+c.
Inputs: app (required), key, keys, repeat, +3 more.
read_app_stateCRead-onlyIdempotent
Compatibility alias for get_app_state.
Inputs: app (required).
request_confirmationADestructive
Create a pending challenge bound to an exact high-risk call. A person must approve it from an independent local TTY before it can authorize the action.
Inputs: arguments (required), tool_name (required), confirmation_token.
right_clickCDestructive
Compatibility alias for click with the right button.
Inputs: app (required), x, y, name, +5 more.
screenshotBRead-onlyIdempotent
Capture an unoccluded screenshot for an app/window, or the visible compositor if no app is passed. Prefer app over low-level target.
Inputs: app, zoom, scale, format, +7 more.
scrollCDestructive
Scroll an element or coordinate in a direction by pages.
Inputs: app (required), direction (required), x, y, +7 more.
security_statusARead-onlyIdempotent
Return the active desktop-control security policy and readiness diagnostics without exposing secrets.
Inputs: no named parameters.
sequenceBDestructive
Run an ordered action sequence. Every step re-enters the ordinary single-tool policy, confirmation, confinement, lease, and audit gateway; nested sequences are rejected.
Inputs: steps (required), dry_run, max_steps, stop_on_error, +1 more.
set_valueCDestructive
Set the value of a settable accessibility element.
Inputs: app (required), value (required), element_index (required), confirmation_token.
triple_clickCDestructive
Compatibility alias for a triple left click.
Inputs: app (required), x, y, name, +5 more.
typeCDestructive
Compatibility alias for type_text.
Inputs: app (required), text (required), method, confirmation_token.
type_intoCDestructive
Atomically resolve and verify an editable target, focus it, refresh state, then input text using auto/AT-SPI/paste/keys.
Inputs: app (required), text (required), nth, match, +11 more.
type_textADestructive
Type literal text into the target app. Use paste_text for multiline, tabular, CSV/TSV, Unicode-heavy, or long text. method=auto prefers a focused AT-SPI editable control, then uses isolated background key/paste input; method=atspi explicitly requests accessibility text insertion.
Inputs: app (required), text (required), method, confirmation_token.
waitCRead-onlyIdempotent
Compatibility alias: wait for a short duration.
Inputs: duration.
wait_for_closeBRead-onlyIdempotent
Wait for a target window/dialog to close. If related_to is provided, return the surviving related/root app state.
Inputs: app, target, timeout, related_to.
wait_for_windowARead-onlyIdempotent
Wait for a Hyprland window or same-process related popup/dialog to appear, then return its app state. Use after actions expected to open dialogs or new windows.
Inputs: app, class, title, timeout, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 45 tools
Roughly a third of the surface is explicit duplicate aliases (open_app=launch_app, read_app_state=get_app_state, get_screenshot=screenshot, list_windows=list_apps, key=press_key, left/right/middle/double/triple_click=click, hover/move_mouse, type=type_text, left_click_drag=drag), so an agent frequently has two or more tools that do the identical thing. Overlaps also exist among non-alias tools: type_text vs type_into vs paste_text vs set_value, and screenshot vs get_app_state. The 'Compatibility alias for X' phrasing helps, but boundaries remain murky.
All names are snake_case with no camelCase mixing, which is good, but verb conventions are inconsistent: verb_noun (get_app_state, list_apps, click_text, manage_window) coexists with bare verbs (click, scroll, drag, hover, panic, wait, sequence) and bare nouns (computer, ocr, screenshot). The name 'computer' for a compatibility tool is especially uninformative and breaks any pattern.
45 tools is far beyond a comfortable set and is inflated by ~14 pure aliases that add no capability. Even discounting aliases, the 30 real tools cover a lot of ground, but the alias bloat makes the surface heavy and hard to scan.
For a Hyprland desktop-control agent the lifecycle is well covered: discovery (list_apps, list_windows), state capture (get_app_state, screenshot, ocr, get_marks), input (click, type_text, paste_text, press_key, scroll, drag, set_value), window/workspace management, and safety (security_status, request_confirmation, panic, audit_replay, sequence). Minor gaps only, e.g. no explicit clipboard read/copy-back or multi-monitor enumeration beyond cursor coordinates.
Related MCP Connectors
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Context and control for any AI. Agent identity, scoped access, and proof across tools.
Agent routing, safety preflight, execution receipts, best execution and verified outcomes.
Preflight, approve, and prove consequential agent actions with signed evidence and x402 tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control a Hyprland Wayland desktop by listing windows, capturing screenshots, and sending input to a dedicated agent workspace without disrupting the user's screen.1MIT
- AlicenseAqualityCmaintenanceEnables background window capture and input automation without moving the cursor or stealing focus, working across Windows, Linux X11, and Wayland systems.6Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables a constrained subagent to perform foreground GUI actions on Hyprlandβobserving, focusing windows, clicking, typing, scrolling, dragging, and managing the clipboardβunder per-action approval with lease, audit log, and kill-switch gating.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to control Hyprland desktops via MCP, including pointer/keyboard input, screenshots, launching apps, and natural-language window targeting using a local decision model.141MIT