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

CommandWhat 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 mcpMCP 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 --listWhat's connected
capturist doctorCheck library access, index and setup
capturist guideHow AI agents should use Capturist

Options

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.