screenagents

Screenshot anything, instantly — no Playwright, no browser, no heavy dependencies.

CLI · Python library · MCP server — one tiny package.

Install · Quick start · Backends · Python API · MCP server · Troubleshooting · Landing page

screenagents is a small, dependency-free Python package that takes screenshots by delegating to the screenshot tool your operating system already ships with. It wraps twelve native backends — screencapture on macOS, PowerShell + System.Drawing on Windows, grim/scrot/maim/ImageMagick and friends on Linux — behind one honest API, one sane CLI, and one MCP tool for agents.

It does not render web pages, boot Chromium, or install a browser engine to take a picture of your desktop.

$ pip install screenagents
$ screenagents
screenshot-20261018-1832-a1b2c3.png

Why

Every OS already knows how to screenshot itself. Most automation stacks ignore that and drag in a headless browser — hundreds of megabytes of runtime to copy pixels that are sitting right there.

If you need to screenshot a web page, use Playwright. If you need a picture of the screen, this is the tool.

Related MCP server: screenshot-mcp

Features

• Zero dependencies. Core is Python stdlib only (subprocess, os, struct).

• Twelve native backends. Detected at runtime, ordered best-first, session-aware (Wayland vs X11), with capability checks for region / monitor / named output.

• Honest failures. Typed exceptions with the backend's own stderr, plus a --doctor command that explains exactly why each backend is or is not available.

• Atomic writes. Captures land in a temporary screenagents-tmp-*.png file and are renamed into place only on success — a failed capture never leaves a half-written PNG or clobbers an existing file.

• Metadata included. Dimensions parsed from the PNG header, byte size, region and backend recorded on every result.

• Agent-ready. Optional MCP server returning the PNG as base64 so multimodal models can actually look at the screen.

• Trivially embeddable. screenshot() is one function; the CLI is one file.

Install

pip install screenagents            # core: CLI + library (Python 3.9+)
pip install "screenagents[mcp]"     # + MCP server (needs Python 3.10+)

Requires Python 3.9+. macOS and Windows need nothing else. On Linux, install one of the backends below — most desktop environments already have one.

Quick start

$ screenagents                          # full screen, timestamped file in cwd
$ screenagents ~/Desktop/shot.png       # choose the path
$ screenagents -r 0,0,800,600           # x,y,width,height
$ screenagents -r 1920x1080+1920+0      # X11 geometry notation
$ screenagents -m 2                     # second monitor (where supported)
$ screenagents -b grim --display DP-1   # force a backend and output
$ screenagents --json                   # machine-readable metadata
$ screenagents --list-backends          # what can run here, and why not
$ screenagents --doctor                 # environment + full diagnostics

--json output:

{
  "path": "screenshot-20261018-1832-a1b2c3.png",
  "backend": "grim",
  "format": "png",
  "bytes": 88214,
  "width": 1024,
  "height": 640,
  "region": "0,0,1024,640"
}

Exit codes: 0 success, 1 capture/backend failure, 2 bad arguments. Only the path (or JSON) goes to stdout, so $(screenagents) is safe in scripts.

Backends

Selection rules, in order: platform matches → session matches (Linux) → binary exists on PATH → requested capabilities are supported → first match wins. Passing --backend NAME skips the search but still validates availability.

Install a Linux backend:

sudo apt install grim       # Wayland (Debian/Ubuntu)
sudo apt install scrot      # X11 (Debian/Ubuntu)
sudo dnf install grim       # Fedora
sudo pacman -S grim         # Arch

Python library

from screenagents import screenshot, Region

shot = screenshot("desktop.png")                       # full screen
shot = screenshot("corner.png", region="0,0,640,480")  # x,y,width,height
shot = screenshot("right.png", region="1920x1080+1920+0", overwrite=True)
shot = screenshot("second.png", monitor=2)             # 1-based

print(shot.width, shot.height, shot.backend, shot.bytes)
print(shot.to_dict())

Screenshot carries path, backend, format, bytes, width, height and region. Errors are typed — catch ScreenAgentsError, or one of NoBackendError, BackendUnavailableError, CaptureError — and always include the backend's stderr when there is one.

MCP server

pip install "screenagents[mcp]"
screenagents-mcp     # stdio transport

Claude Desktop / Cursor / any MCP client:

{
  "mcpServers": {
    "screenagents": {
      "command": "screenagents-mcp"
    }
  }
}

Errors come back as {"ok": false, "error": "…"} instead of raising, so an agent can read the reason and pick another backend.

How it works

   cli · library · mcp
           │
           ▼
      capture.py ─────── atomic temp file, size from the png header
           │
           │  CaptureRequest(region, monitor, display)
           ▼
      backends.py ────── platform + session detection, best-first order
           │
           │  argv
           ▼
      the OS tool ────── screencapture · powershell · grim · scrot · maim
                         import · gnome-screenshot · spectacle · flameshot

No server, no port, no daemon. The only permission involved is the screen-recording permission your OS already enforces.

Troubleshooting

"no working screen-capture backend found" — run screenagents --doctor. On Linux it prints your session (x11/wayland) and what to install. On Wayland, grim is the usual answer; on X11, scrot.

macOS captures a black image or nothing — grant Screen Recording permission to your terminal in System Settings → Privacy & Security → Screen Recording, then restart the terminal.

A region flag is rejected — the auto-selected backend cannot crop. Let detection pick a region-capable one (drop --backend), or use a backend marked ✅ above.

PNG is fine but dimensions are null — dimensions are read from the PNG header; non-PNG output still works, it just has no size metadata.

Landing page

The project's landing page lives in site/: React + Vite, ASCII art throughout, light and dark themes, one page per topic — deployed to Cloudflare Pages at https://screenagents.pages.dev.

cd site
npm install
npm run dev       # local development
npm run build     # static build in site/dist
npx wrangler pages deploy dist --project-name screenagents

Development

git clone https://github.com/Parithosh-Varma/screenagents
cd screenagents
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,mcp]"
pytest -q

The test suite runs on any OS: backend detection and command construction are tested with sys.platform, shutil.which and the session environment patched, and the capture pipeline is exercised with a fake backend. A real capture test runs when a backend is available and skips otherwise — which is why CI is green on headless runners.

See CONTRIBUTING.md to add a backend.

Contributing

Issues and pull requests are welcome. Please run pytest -q before opening a PR and include screenagents --doctor output in backend-related bug reports.

License

MIT © 2026 Parithosh Varma