capturist: command line and MCP server
The capturist command gives scripts and AI agents your Capturist screenshots, snippets and clipboard, and runs the MCP server that Claude, ChatGPT, Codex and other AI apps use. It works with every Capturist on your Mac.
Install
curl -fsSL https://capturist.nodetools.org/install-cli.sh | bash
Installs to ~/.local/bin/capturist after checking the download's checksum and signature. Run it again to update. Universal (Apple silicon and Intel), macOS 14 or later.
Or with Homebrew:
brew install vortex-303/tap/capturist
It's also in the official MCP Registry as io.github.vortex-303/capturist-mcp, with a one-click bundle for Claude desktop (capturist.mcpb, on the latest release).
Commands
| Command | What it does |
|---|---|
capturist recent [--since 2h] [--kind image|text|pdf] [--limit 20] | Newest captures |
capturist search <words…> | Search names, source app, window title and the text inside images |
capturist show <ref> | Details and the file path (open it to see the image) |
capturist text <ref> | The text inside a capture, read on this Mac |
capturist clips [--since 1h] | Clipboard history, if turned on in Capturist |
capturist index [--force] | Update the text index (search does this itself) |
capturist mcp | MCP server over stdio: relays to the running app (all tools), else reads the library |
capturist setup <target> | Connect claude-desktop, chatgpt, claude-code, codex, cursor, opencode, or set the shortcut (⌥⌘7 saves selected text) |
capturist setup --list | What's connected |
capturist doctor | Check library access, index and setup |
capturist guide | How AI agents should use Capturist |
Options
--json: machine-readable output with stable fields: id, shortId, created, kind, name, app, title, url, path, width, height, size, shareUrl, text.--library store|complete|dev|<path>: which library. Default: the running app's, else the one used most recently. AlsoCAPTURIST_LIBRARY.
Refs
latest, latest~1 (the one before), or the first characters of an id, such as 3f9a2c1b.
Exit codes
0 ok · 1 nothing found · 2 bad input · 3 library missing or not readable.
Examples
capturist recent --since 30m
capturist search "invoice 502" --json
capturist text latest
capturist setup shortcut --key "⌥⌘7"
More
Connecting AI apps step by step: Capturist for Claude, ChatGPT and Codex. Machine-readable facts: capturist.json. Source code (MIT): github.com/vortex-303/capturist-mcp.