hypruse MCP Server

Name: hypruse MCP Server
Author: io.github.IlyasKhallouki

io.github.IlyasKhallouki/hypruse

Repository Registry

What is the hypruse MCP server?

Computer use for Hyprland: semantic desktop state over IPC, plus vision and native input

How to install hypruse

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

HYPRUSE_SCREENSHOT_MODE
How captures are returned: 'file' writes to XDG_RUNTIME_DIR and returns the path, 'image' returns the image inline. Use 'image' for clients that render MCP images but cannot read files, such as Claude Desktop.
HYPRUSE_READONLY
Set to 1 to expose only the observation tools (desktop, screenshot, zoom, ui, marks, binds, wait_for). The agent can see and narrate but cannot click, type, or launch.
HYPRUSE_CONFINE
Restrict input to a scope of windows and refuse everything outside it: 'launched' (only windows hypruse opened this session), 'class:firefox,kitty', or 'workspace:3,special:notes'. Unset means no confinement.
HYPRUSE_AUTH_GUARD
Refuse to click or type into system authentication dialogs (polkit, keyring prompts). On by default; 'strict' also refuses password fields in ordinary windows; 0 disables it.
HYPRUSE_STRICT
Set to 1 to refuse to act when the cursor or focused window moved since hypruse's last action, so the agent must re-read the desktop before retrying.
HYPRUSE_MARK
Set to 1 to make the agent's presence legible: tag every window it opens 'hypruse-owned' and flash an on-screen notice when it opens a window or captures the screen.
HYPRUSE_CLIPBOARD
Set to 1 to register the opt-in clipboard tool (never in read-only mode). Off by default because clipboards hold passwords.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hypruse": {
      "command": "uvx",
      "args": [
        "hypruse"
      ],
      "env": {
        "HYPRUSE_SCREENSHOT_MODE": "<YOUR_HYPRUSE_SCREENSHOT_MODE>",
        "HYPRUSE_READONLY": "<YOUR_HYPRUSE_READONLY>",
        "HYPRUSE_CONFINE": "<YOUR_HYPRUSE_CONFINE>",
        "HYPRUSE_AUTH_GUARD": "<YOUR_HYPRUSE_AUTH_GUARD>",
        "HYPRUSE_STRICT": "<YOUR_HYPRUSE_STRICT>",
        "HYPRUSE_MARK": "<YOUR_HYPRUSE_MARK>",
        "HYPRUSE_CLIPBOARD": "<YOUR_HYPRUSE_CLIPBOARD>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "hypruse": {
      "command": "uvx",
      "args": [
        "hypruse"
      ],
      "env": {
        "HYPRUSE_SCREENSHOT_MODE": "<YOUR_HYPRUSE_SCREENSHOT_MODE>",
        "HYPRUSE_READONLY": "<YOUR_HYPRUSE_READONLY>",
        "HYPRUSE_CONFINE": "<YOUR_HYPRUSE_CONFINE>",
        "HYPRUSE_AUTH_GUARD": "<YOUR_HYPRUSE_AUTH_GUARD>",
        "HYPRUSE_STRICT": "<YOUR_HYPRUSE_STRICT>",
        "HYPRUSE_MARK": "<YOUR_HYPRUSE_MARK>",
        "HYPRUSE_CLIPBOARD": "<YOUR_HYPRUSE_CLIPBOARD>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "hypruse": {
      "command": "uvx",
      "args": [
        "hypruse"
      ],
      "env": {
        "HYPRUSE_SCREENSHOT_MODE": "<YOUR_HYPRUSE_SCREENSHOT_MODE>",
        "HYPRUSE_READONLY": "<YOUR_HYPRUSE_READONLY>",
        "HYPRUSE_CONFINE": "<YOUR_HYPRUSE_CONFINE>",
        "HYPRUSE_AUTH_GUARD": "<YOUR_HYPRUSE_AUTH_GUARD>",
        "HYPRUSE_STRICT": "<YOUR_HYPRUSE_STRICT>",
        "HYPRUSE_MARK": "<YOUR_HYPRUSE_MARK>",
        "HYPRUSE_CLIPBOARD": "<YOUR_HYPRUSE_CLIPBOARD>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "hypruse": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "hypruse"
      ],
      "env": {
        "HYPRUSE_SCREENSHOT_MODE": "<YOUR_HYPRUSE_SCREENSHOT_MODE>",
        "HYPRUSE_READONLY": "<YOUR_HYPRUSE_READONLY>",
        "HYPRUSE_CONFINE": "<YOUR_HYPRUSE_CONFINE>",
        "HYPRUSE_AUTH_GUARD": "<YOUR_HYPRUSE_AUTH_GUARD>",
        "HYPRUSE_STRICT": "<YOUR_HYPRUSE_STRICT>",
        "HYPRUSE_MARK": "<YOUR_HYPRUSE_MARK>",
        "HYPRUSE_CLIPBOARD": "<YOUR_HYPRUSE_CLIPBOARD>"
      }
    }
  }
}

Claude Code

claude mcp add hypruse --env HYPRUSE_SCREENSHOT_MODE=<YOUR_HYPRUSE_SCREENSHOT_MODE> --env HYPRUSE_READONLY=<YOUR_HYPRUSE_READONLY> --env HYPRUSE_CONFINE=<YOUR_HYPRUSE_CONFINE> --env HYPRUSE_AUTH_GUARD=<YOUR_HYPRUSE_AUTH_GUARD> --env HYPRUSE_STRICT=<YOUR_HYPRUSE_STRICT> --env HYPRUSE_MARK=<YOUR_HYPRUSE_MARK> --env HYPRUSE_CLIPBOARD=<YOUR_HYPRUSE_CLIPBOARD> -- uvx hypruse