Skip to main content
Glama
zelentsov-dev

ClipSnap

by zelentsov-dev
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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 viaCtrl+V in iTerm2 is unreliable and often fails completely.

These are real, open issues:

Issue

What happens

claude-code#29776

Ctrl+V image paste fails silently — "No image found in clipboard"

claude-code#17042

sandbox-exec blocks clipboard access via com.apple.hiservices-xpcservice

claude-code#29365

Ctrl+V image paste in iTerm2 intermittently fails (still reproducible)

claude-code#1361

"Can't paste image from clipboard" (various causes)

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.

Related MCP server: MCP Windows Screenshots

The Solution

Real-Time Capture

A lightweight Swift daemon polls NSPasteboard every 500ms. Clipboard-only screenshots (Shottr Esc, Cmd+C on any image) are captured automatically as PNG files.

Multi-Source Discovery

Parallel search across clipboard watcher dir, native macOS screenshots dir, and Spotlight. Three sources — the newest image wins.

Sandbox Bypass

MCP servers run outside sandbox-exec. No more denied clipboard access. No more silent failures.

Smart Processing

Auto-resize to optimal AI vision dimensions (1568px). Saves tokens without losing detail. PNG or JPEG output.

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.

Parameter

Type

Default

Description

count

number (1–10)

3

Number of images to return

folder

string

—

Scan a specific folder instead

max_dimension

number

1568

Max long edge in pixels

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.

Parameter

Type

Default

Description

all

boolean

false

Delete ALL sessions, not just current

older_than_minutes

number

—

Delete files older than N minutes

Configuration

All settings via environment variables:

Variable

Default

Description

CLIPSNAP_MAX_DIMENSION

1568

Max image long edge (px)

CLIPSNAP_IMAGE_FORMAT

png

Output format (png or jpeg)

CLIPSNAP_JPEG_QUALITY

80

JPEG quality (1–100)

CLIPSNAP_SCREENSHOTS_DIR

auto

Native screenshots dir (auto-detected via defaults read com.apple.screencapture)

CLIPSNAP_MAX_FILES

50

Max files per session

CLIPSNAP_TTL_MINUTES

60

File time-to-live

CLIPSNAP_MAX_SIZE_MB

200

Max total session size

CLIPSNAP_CHECK_CONCEALED

true

Detect passwords before reading clipboard

CLIPSNAP_CLEANUP_ON_EXIT

true

Delete session files on exit

Token Cost

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

Image Size

Tokens

Cost (Sonnet, $3/1M input)

1568x882 (16:9)

~1,841

$0.006

1568x1024

~2,141

$0.006

800x600 (snippet)

~640

$0.002

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

The Swift watcher binary must be built:

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

If the binary is missing, ClipSnap still works via Spotlight and native dir scanning — just without real-time clipboard capture.

Take a screenshot or copy an image first:

  • Cmd+Shift+4 (region) or Cmd+Shift+3 (full screen)

  • Cmd+C on an image in Preview, Figma, browser

  • Shottr, CleanShot X, or any screenshot tool

Your clipboard contains a password (1Password, Bitwarden, etc.). ClipSnap refuses to read it for security. Copy a screenshot instead.

ClipSnap auto-detects from defaults read com.apple.screencapture location, falling back to ~/Screenshots or ~/Desktop. Override with CLIPSNAP_SCREENSHOTS_DIR.

Contributing

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

Built by Aleksei Zelentsov

Available Tools

2 tools
cleanup_imagesCleanup Session ImagesA
DestructiveIdempotent

Deletes temporary ClipSnap images from the session temp directory. Automatic cleanup already runs on TTL/size limits, so this is rarely needed. Use all=true to purge all sessions.

ParametersJSON Schema
NameRequiredDescriptionDefault
allNoDelete ALL sessions, not just current (default: false)
older_than_minutesNoOnly delete files older than N minutes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about automatic cleanup but does not disclose further behavioral traits such as confirmation requirements or effects on other users. Given annotations, the description provides adequate but not rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The first sentence states the primary purpose, and the second provides usage guidance. Highly efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (2 optional params, no output schema) and annotations covering destructive and idempotent traits, the description covers purpose, usage frequency, and a parameter hint. It does not describe return behavior, but this is a minor omission for a simple cleanup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. The description adds meaning for the 'all' parameter ('use all=true to purge all sessions'), but does not enhance understanding of 'older_than_minutes' beyond the schema. With full coverage, baseline is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Deletes temporary ClipSnap images from the session temp directory' using a specific verb and resource, and distinguishes itself from automatic cleanup, which effectively differentiates it from the sibling tool 'paste_recent'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Automatic cleanup already runs on TTL/size limits, so this is rarely needed', providing clear guidance on when to use this tool versus relying on automatic cleanup. Also advises using 'all=true' for purging all sessions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

paste_recentPaste Recent ScreenshotsA
Read-only

Shows the last N images by combining clipboard watcher captures, session history, and macOS Spotlight screenshots. The clipboard watcher catches images copied via any app (Shottr Esc, Cmd+C, etc.) instantly — no Spotlight delay. Results are sorted by time, newest first. Use when the user says "show my last screenshots", "look at my clipboard", or "check what I just captured". Pass folder to scan a specific directory instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNoNumber of images to return (default: 3)
folderNoScan a specific folder instead of session + Spotlight
max_dimensionNoMax long edge in pixels (default: 1568)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description explains the tool combines three sources, sorts by time, and notes clipboard watcher avoids Spotlight delay. This adds useful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences with no redundancy. Information is front-loaded: purpose in first sentence, usage guidance in third, parameter nuance in fourth. Every sentence is meaningful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only tool with no output schema, the description covers purpose, usage, and parameter behavior. It does not describe return format or error cases, but the readOnlyHint and simplicity make this acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters are fully described in the input schema (100% coverage), including defaults and folder behavior. The description adds minimal additional meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shows recent images from multiple sources, with a specific verb and resource. It distinguishes from sibling tool 'cleanup_images' by focusing on retrieval vs cleanup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use examples ('show my last screenshots', 'look at my clipboard') and a usage alternative (pass folder). Lacks explicit when-not-to-use compared to sibling, but the examples are clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

The two tools have completely distinct purposes: one deletes temporary images, the other retrieves recent images. There is no ambiguity or overlap.

Naming Consistency4/5

Both tools use snake_case with verb_noun pattern, though 'paste_recent' uses an adjective. The naming is mostly consistent and predictable.

Tool Count3/5

With only 2 tools, the server feels under-scoped for an image management utility. It is borderline but not an extreme mismatch.

Completeness2/5

The tool surface lacks obvious features like capturing, editing, or listing images, leaving significant gaps for typical image-related tasks.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Maccy Clipboard MCP

    vlad-ds
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives Claude and other AI assistants access to your Maccy clipboard history, allowing search, retrieval, and management of copied content through natural conversation.
    9

  • mcp-clipboard

    cmeans
    A
    license
    A
    quality
    B
    maintenance
    MCP server that reads and writes the system clipboard — tables, text, code, JSON, URLs, images, and more. Preserves spreadsheet structure (rows/columns) that is lost when pasting into Claude directly.
    4
    5
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zelentsov-dev/clipsnap-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server