zeuxis

Zeuxis is a local MCP screenshot server that lets AI agents capture the current desktop, windows, cursor regions, and exact rectangles through MCP tools.

It runs as one local binary over stdio by default. Capture results stay on the machine as managed image artifacts and are returned to the MCP client as file:// resource links plus structured metadata. Zeuxis does not upload screenshots, perform OCR, drive the UI, or expose system-control tools.

Supported platforms

Choose a capture tool

For deterministic window capture, call list_windows and pass both snapshot_id and window_id from that same response to capture_window. Window IDs are scoped to the snapshot, not durable across listings.

MCP tools

Tool schemas are defined in src/mcp/tools.rs. Result payloads are built in src/mcp/result.rs, and stable errors are defined in src/mcp/errors.rs.

Shared capture parameters:

Examples:

{ "delay_ms": 800, "play_sound": true }

{ "output": "compact" }

{
  "output": {
    "mode": "custom",
    "format": "webp",
    "max_dimension": 2048
  }
}

Output options

Preset output modes:

Custom output mode:

If ZEUXIS_ARTIFACT_HMAC_KEY is set, capture results also include artifact_hmac_sha256.

Coordinates and limits

Coordinate inputs use logical desktop points. Captured image dimensions use source pixels. Use the returned input_units, source_units, and source_scale_factor fields to reason about HiDPI scaling.

Runtime limits:

Requested delays run before capture work and are additive to the capture timeout. For example, a request with delay_ms=30000 and the default --blocking-task-timeout-ms=15000 can take up to about 45 seconds before the client receives a timeout or result.

Platform permissions

macOS

Zeuxis checks Screen Recording permission before capture. If permission is missing, Zeuxis asks macOS for access and returns permission_denied for that same tool call. Grant Screen Recording permission to the terminal or host app that starts Zeuxis, then retry the tool call.

Cursor-dependent tools read the global cursor position and may also require Accessibility permission. If those fail, try capture_screen or capture_rect while you update permissions.

Linux

Linux capture support depends on the graphical session and backend capabilities. If capture fails, call get_runtime_diagnostics and check xdg_session_type, display, wayland_display, monitors_ok, and cursor_ok.

On Wayland, cursor and window capture behavior can be more limited than full-screen capture. Prefer capture_screen first, then narrow to regions if the compositor allows it.

Privacy and safety

Zeuxis is designed for local observation:

• It serves MCP over local stdio.
• It returns local file:// artifact links.
• It does not upload screenshots to remote services.
• It does not perform OCR, UI element detection, input automation, shell execution, or window control.
• It validates tool parameters before capture.
• Capture work runs in a subprocess worker with parent-enforced timeout and termination.
• clear_session_artifacts deletes only Zeuxis-managed artifacts from the current session.

Managed artifact files use the zeuxis- prefix and .png, .jpg, or .webp suffix. Retention pruning is best effort and never deletes the artifact currently being returned.

Development

Useful source entrypoints:

Run local checks:

cargo check
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets

On Ubuntu/Linux CI-like environments, install the capture backend build dependencies first:

sudo apt-get update
sudo apt-get install -y \
  pkg-config \
  libclang-dev \
  libxcb1-dev \
  libxrandr-dev \
  libdbus-1-dev \
  libpipewire-0.3-dev \
  libwayland-dev \
  libegl-dev \
  libdrm-dev \
  libgbm-dev

This repo also ships a prek.toml for lightweight local commit gates:

prek validate-config
prek run --all-files
prek install

The configured hooks run cargo fmt --all -- --check and cargo clippy --all-targets --all-features -- -D warnings.

Install

Use one of the following install paths.

Cargo

Requires Rust 1.88 or newer.

cargo install zeuxis
zeuxis --version

Homebrew

brew install bnomei/zeuxis/zeuxis
zeuxis --version

GitHub Releases

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

Verify the binary:

zeuxis --help

From source

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

Quickstart

Add Zeuxis to an MCP client as a stdio server:

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

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

After the client connects, call get_runtime_diagnostics first. A healthy result reports permission_ok=true and monitors_ok=true. Then call capture_screen for the first screenshot.

Successful capture tools return:

• a short text summary,
• a file:// resource link to the local artifact,
• structured fields such as path, uri, output_format, mime_type, artifact_sha256, width, height, capture_mode, captured_at_utc, source_scale_factor, and target.

Configuration

Configuration is resolved as CLI flag > environment variable > default. Zeuxis does not read config files.

Runtime configuration lives in src/runtime_config.rs.

Example:

ZEUXIS_MAX_CONCURRENT_CAPTURES=4 \
ZEUXIS_MAX_ARTIFACTS=128 \
zeuxis --blocking-task-timeout-ms 30000

Troubleshooting

permission_denied

Cause: The OS denied screen capture permission.

Fix:

1. On macOS, grant Screen Recording permission to the terminal or MCP host app.
2. Retry the same tool call after granting permission.

Verify:

1. Call get_runtime_diagnostics.
2. Confirm permission_ok=true.

cursor_unavailable

Cause: Zeuxis could not read the global cursor position.

Fix:

1. Grant Accessibility permission if your platform requires it.
2. Use capture_screen, capture_active_window, or capture_rect when cursor position is unavailable.

window_not_found

Cause: The focused window, cursor window, or requested snapshot window is no longer available.

Fix:

1. Call list_windows again.
2. Retry with a fresh snapshot_id and window_id, or fall back to capture_screen.

invalid_region

Cause: The requested rectangle is outside supported bounds or exceeds the size limits.

Fix:

1. Check monitor bounds with list_monitors.
2. Reduce width and height.
3. Keep the capture area at or below 40000000 pixels.

no_capture_yet

Cause: get_latest_capture was called before this server session captured an artifact.

Fix:

1. Call a capture_* tool first.
2. Retry get_latest_capture.

storage_failed

Cause: Artifact write, retention cleanup, worker IPC, or timeout handling failed.

Fix:

1. Check that ZEUXIS_ARTIFACT_DIR is writable, if set.
2. Increase --blocking-task-timeout-ms for slow captures.
3. Retry the capture. Timed-out worker processes are terminated and reaped before Zeuxis returns.

License

Zeuxis is licensed under the MIT License.