zeuxis

Zeuxis is a local, read-only MCP screenshot server that lets AI agents capture screenshots themselves.

When your MCP client connects to Zeuxis, the agent can call screenshot tools directly (full screen, active window, cursor region, or exact rect), then immediately use the returned file:// image link and metadata in its next reasoning step. No manual screenshot/upload handoff is required.

Zeuxis is:

• CLI-first: one local binary, stdio MCP transport by default.
• MCP-first: explicit tool schemas and stable error codes.
• Safety-first: strict input validation, bounded capture concurrency, and temp-file retention limits.

Supported platforms in v1:

• macOS (first-class)
• Linux (best-effort; backend/compositor dependent)

Installation

Cargo (crates.io)

cargo install zeuxis

Homebrew

brew install bnomei/zeuxis/zeuxis

GitHub Releases

Download a prebuilt archive from GitHub Releases, extract it, and place zeuxis on your PATH.

From source

git clone https://github.com/bnomei/zeuxis.git
cd zeuxis
cargo build --release

Quickstart

Run MCP over stdio

zeuxis
# or
cargo run --quiet

Show CLI options

zeuxis --help
zeuxis --version

MCP client configuration example

{
  "mcpServers": {
    "zeuxis": {
      "command": "zeuxis",
      "args": []
    }
  }
}

Add Zeuxis via CLI commands

If you use Codex CLI:

codex mcp add zeuxis -- zeuxis
codex mcp list

If you use Amp CLI:

amp mcp add zeuxis -- zeuxis
amp mcp list

MCP Tools

Shared params for capture_* tools:

• delay_ms or delay_seconds (use one), play_sound, and optional output settings.
• output accepts either a preset string ("analysis"|"exact"|"compact") or an object ({ "mode":"preset|custom", ... }).

Notes:

• Coordinate inputs are logical desktop points; resulting image dimensions are source pixels.
• Capture results include local file:// artifact links plus metadata like capture_mode, artifact_capture_mode, dimensions, hashes, and source_scale_factor.
• Errors are structured with error_code, message, and retryable.

Runtime Safety Limits

• delay_ms max: 30000
• delay_seconds max: 30
• capture dimension max: 16384 x 16384
• capture area max: 40,000,000 pixels
• capture work runs in a dedicated subprocess worker and is gated by a semaphore
• capture timeout is enforced in the parent process; timed-out workers are terminated and reaped before returning
• capture timeout: configurable (100..=300000 ms, default 15000 ms)

Temp artifact retention:

• managed files use prefix zeuxis- and suffix .png, .jpg, or .webp
• older artifacts are pruned on each successful write
• pruning is best effort and never deletes the current artifact being returned

Configuration

Precedence is CLI flag > env var > default (no config files).

macOS Permissions

On macOS, Zeuxis preflights Screen Recording permission before each capture.

If permission is missing, Zeuxis requests access via CoreGraphics and returns permission_denied for that same invocation (no same-call retry). After granting access, call the tool again.

Cursor-dependent tools may also require Accessibility permission because they read global cursor position.

Linux Notes

On Linux, Zeuxis does not run a dedicated permission preflight gate in v1. Capture behavior depends on your desktop environment/compositor and what the underlying capture backend permits.

If cursor-dependent tools fail (especially on Wayland), run get_runtime_diagnostics first and fall back to capture_screen or capture_rect as needed.

Development

cargo check
cargo fmt --all --check
cargo clippy --all-targets --all-features
cargo test --all-targets
cargo audit

See:

• operations
• homebrew notes
• overview
• specs