ClipSnap

Reliable clipboard image paste for Claude Code in iTerm2

Quick Start  •   How It Works  •   Tools  •   Config  •   Troubleshooting

An MCP server that gives Claude Code reliable access to clipboard images and screenshots. A background Swift daemon watches the clipboard in real time, so screenshots from any app — including clipboard-only tools like Shottr — are captured automatically and available instantly.

Built to fix the broken Ctrl+V image paste in iTerm2 and Terminal.app when using Claude Code. Should also work with any MCP-compatible client (Cursor, Claude Desktop, etc.).

The Problem

[!WARNING] Pasting images into Claude Code via Ctrl+V in iTerm2 is unreliable and often fails completely.

These are real, open issues:

Similar problems exist in other terminal AI tools: Codex CLI, Gemini CLI. The root cause is that terminals have no reliable protocol for transferring binary image data from the macOS clipboard.

The Solution

Quick Start

Install

git clone https://github.com/zelentsov-dev/clipsnap-mcp.git ~/.clipsnap-mcp
cd ~/.clipsnap-mcp
npm install
npm run build        # TypeScript + Swift clipboard watcher
npm install -g .     # install globally (symlinks to this directory)

Important: npm install -g . creates a symlink to the cloned directory — do not delete it. npm install -g git+https://... does not work because the package requires a build step.

Add to Claude Code

claude mcp add --scope user --transport stdio clipsnap -- clipsnap-mcp

This registers ClipSnap globally across all your projects. Verify with:

claude mcp list

Then restart Claude Code. Now when you say "look at my screenshot" or "check what I just captured", Claude Code will use ClipSnap to find your images.

Update

cd ~/.clipsnap-mcp
git pull
npm install          # if dependencies changed
npm run build

The global clipsnap-mcp binary is a symlink to ~/.clipsnap-mcp, so it picks up changes automatically. Restart Claude Code after updating.

Uninstall

claude mcp remove clipsnap --scope user
npm uninstall -g clipsnap-mcp
rm -rf ~/.clipsnap-mcp

How It Works

1. Claude Code starts
   └── MCP server starts
       └── Swift clipboard watcher spawns as background daemon

2. User takes screenshot (any app: native, Shottr, CleanShot X, browser, etc.)
   └── Clipboard gets image
       └── Watcher detects NSPasteboard change within ~500ms
           └── Saves PNG to ~/.clipsnap/clipboard-captures/

3. User: "look at my screenshot"
   └── Claude Code calls paste_recent tool
       └── Parallel search:
           ├── Watcher captures dir    (clipboard images, instant)
           ├── Native screenshots dir  (file-saved screenshots, instant)
           └── Spotlight mdfind        (broad coverage, all apps)
       └── Merge, dedup, sort by time → return newest N as base64 images

4. Claude Code exits
   └── SIGTERM → watcher stops → session files cleaned up

graph TD
    A["Claude Code"] -->|MCP stdio| B["ClipSnap MCP Server<br/>(Node.js)"]
    B -->|spawns on start| C["Swift Clipboard Watcher"]
    C -->|polls NSPasteboard<br/>every 500ms| D["~/.clipsnap/clipboard-captures/"]
    B -->|scans| D
    B -->|scans| E["Native Screenshots Dir"]
    B -->|queries| F["Spotlight mdfind"]
    D & E & F -->|merge + dedup<br/>sort by time| G["Return newest N images"]
    A -->|SIGTERM on exit| C

Tools Reference

paste_recent

Returns the most recent N screenshot images. Combines clipboard watcher captures, native macOS screenshots directory, and Spotlight. Sorted by time, newest first.

Example prompts: "Look at my screenshot", "Compare the last 4 screenshots", "Check what I just captured"

cleanup_images

Deletes temporary ClipSnap session images. Auto-cleanup runs on TTL/size limits, so this is rarely needed.

Configuration

All settings via environment variables:

Token Cost

Claude calculates image tokens as (width x height) / 750:

Security

• Password detection — checks ConcealedType / TransientType before reading (1Password, Bitwarden, macOS Keychain)
• Symlink protection — lstat prevents following symlinks to sensitive files
• File permissions — 0600 files, 0700 directories
• Session isolation — UUID-based subdirs per process ($TMPDIR/clipsnap-<uuid>/)
• No content logging — clipboard data is never logged
• No network calls — fully offline, zero telemetry

Compatibility

Built and tested with Claude Code on iTerm2 on macOS.

Since ClipSnap is a standard MCP server (stdio transport), it should work with any MCP-compatible client — Cursor, Claude Desktop, Windsurf, etc. — but these haven't been tested yet. If you try it, let us know.

Requirements:

• macOS 15+ (Sequoia or later)
• Node.js 20+
• Swift 6.2+ (for building the clipboard watcher; optional)

Troubleshooting

npm run build   # or: cd watcher && swift build -c release

Contributing

Contributions welcome! Please open an issue before starting work on large changes.