eyes-mcp

Temporary visual eyes for agents on Hyprland/Wayland. Lets Claude (or any MCP client) capture monitors, windows, or arbitrary regions and see the result as a PNG — closing the QA loop without relying on Playwright or screen-share heuristics.

Captures live in a per-process tempdir (/tmp/eyes-mcp-{pid}/) and self-destruct after a TTL (default 60s). Each capture tool returns metadata with a path; read that file to view the image. Capturing and looking are separate steps on purpose — you can take several captures and only spend tokens on the ones worth inspecting — but the TTL is running, so read what you need promptly.

Why

Agents writing UI fixes, desktop scripts, theming tweaks, notebook plots, or anything that produces a visual artifact normally have no way to verify the result. They commit blind, declare success, and the human catches the regression. eyes-mcp gives them a quick, scoped peek so they can self-correct before claiming "done".

Related MCP server: hyprland-mcp-server

Requirements

• Hyprland (Wayland) — uses hyprctl for window/monitor enumeration

• grim — Wayland screenshot backend

• Python 3.11+

• Pillow (image resize)

• uv — required by the plugin install path (see below)

# Arch
sudo pacman -S grim hyprland

Install

cd ~/Projects/mcp/eyes-mcp
pip install -e .

Install as plugin

claude plugin install eyes --marketplace Rixmerz/claude-plugins

Pulls the whole repo via source: github, launches the server with uv run --project ${CLAUDE_PLUGIN_ROOT} eyes-mcp — resolves deps from pyproject.toml on first run, no pip install -e . needed.

First-launch timeout risk: on a cold uv cache, resolving and installing all deps (fastmcp, pillow, pydantic, transitively ~70 packages) has measured up to ~90s before the server reports ready. Claude Code's default MCP startup timeout is 30s, so the very first launch after claude plugin install eyes can time out. Work around it by warming the cache once before registering the plugin:

uv sync --project ~/.claude/plugins/cache/rixmerz/eyes/0.1.1

The cache path uses the plugin name (eyes), not the repo name — adjust the version to match what you installed. Or run uv sync --project <path> against a manual checkout. Subsequent launches use the warmed uv cache and start well under the timeout.

Register with Claude Code

claude mcp add eyes -- python -m eyes_mcp

Or in ~/.config/claude/mcp.json (or equivalent):

{
  "mcpServers": {
    "eyes": {
      "command": "python",
      "args": ["-m", "eyes_mcp"],
      "env": {
        "EYES_TTL_SECONDS": "60",
        "EYES_MAX_SIDE_PX": "1920"
      }
    }
  }
}

Tools

Each capture tool returns a JSON metadata blob (id, path, dims, bytes, ttl). Read the file at path to view the PNG.

capture_window fails rather than guessing when the target window is on a workspace that is not currently displayed: grim reads the composited output, so capturing a hidden window would silently return the visible workspace's pixels under the requested window's name. It also cannot see through an occluding window stacked on top of the target — what you get is what is on screen.

Config

Lifecycle

• Tempdir created on startup: /tmp/eyes-mcp-{pid}/

• Background sweeper deletes expired files every TTL/4 seconds

• atexit wipes the whole tempdir on clean shutdown

• All captures are PNG; downscaled in-place via Pillow LANCZOS

Limitations

• Wayland-only (relies on grim + hyprctl). No X11, macOS, Windows.

• No webcam capture in v1 (intentional scope cut).

• Region selection is non-interactive — agents can't drive slurp. Use capture_window or pass coords directly.

• Multi-monitor coords are global (Hyprland's compositor space).

License

MIT