Skip to main content
Glama

MCP Clipboard Image Server

A Model Context Protocol (MCP) server that enables Claude Code to paste images directly from your system clipboard for instant analysis and processing.

License: MIT Node.js Version Claude Code

Features

  • 🖼️ Paste images directly from clipboard (Ctrl+C/Cmd+C → MCP tool)

  • 🔄 Cross-platform support (Windows, macOS, Linux)

  • 📁 Automatic temporary file creation with accessible paths

  • 🎨 Support for multiple image formats (PNG, JPEG, GIF, BMP, TIFF)

  • ⚡ Format conversion capabilities

  • 🛡️ Robust error handling and user feedback

  • 🔍 Automatic format detection via magic numbers

Related MCP server: view-image-mcp

Installation

npm install
npm run build

Dependencies

  • System Dependencies: The server requires platform-specific clipboard utilities:

    • macOS: Built-in osascript support, optional pngpaste for enhanced functionality

    • Linux: xclip (X11) or wl-paste (Wayland)

    • Windows: Built-in PowerShell support

Linux Setup

# For X11-based systems
sudo apt-get install xclip

# For Wayland-based systems
sudo apt-get install wl-clipboard

macOS Setup (Optional Enhancement)

# Install pngpaste for better clipboard handling
brew install pngpaste

Usage

🚀 Quick Start for Claude Code

Step 1: Install the Server

# Clone and build
git clone https://github.com/yourusername/mcp-clipboard-image-server.git
cd mcp-clipboard-image-server
npm install
npm run build

Step 2: Add to Claude Code

Choose one of these methods:

claude mcp add clipboard-image -s project -- node /absolute/path/to/mcp-clipboard-image-server/dist/index.js

Method B: User scope (Global - Available everywhere)

claude mcp add clipboard-image -s user -- node /absolute/path/to/mcp-clipboard-image-server/dist/index.js

Method C: Local scope

claude mcp add clipboard-image -s local -- node /absolute/path/to/mcp-clipboard-image-server/dist/index.js

Method D: Manual configuration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "clipboard-image": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-clipboard-image-server/dist/index.js"],
      "env": {}
    }
  }
}

Step 3: Restart Claude Code

Restart Claude Code to load the new MCP server.

Step 4: Test it!

  1. Copy any image to clipboard

  2. In Claude Code, say: "paste image"

  3. Claude will automatically capture and analyze your image!

🎯 Claude Code Usage Examples

Basic Usage

User: paste image
Claude: [Captures image and describes what's in it]

User: paste image and help me debug this error
Claude: [Analyzes screenshot of error and provides solutions]

User: paste image and explain this diagram
Claude: [Interprets technical diagrams, flowcharts, etc.]

Command Shortcuts

Claude Code Slash Commands

# Setup slash commands in Claude Code
./setup-claude-commands.sh

# Now you can use in Claude Code:
/pasteimage             # Paste and analyze image
/pasteimage --debug     # Paste and debug errors  
/pasteimage --explain   # Paste and explain diagrams
/pi                     # Quick shortcut

Shell Commands

# Install shell commands
./install-commands.sh

# Use from terminal:
paste-image --debug     # Paste and debug errors
paste-image --explain   # Paste and explain diagrams
pi                      # Quick alias for paste-image

Advanced Usage

  • Screenshots: Perfect for debugging UI issues, error messages

  • Diagrams: Architecture diagrams, flowcharts, wireframes

  • Code snippets: Screenshots of code for review and suggestions

  • Data visualizations: Charts, graphs, analytics dashboards

Available Tools

paste_image

Captures an image from the system clipboard and saves it to a temporary file.

Parameters:

  • filename (optional): Custom filename without extension (UUID generated if not provided)

  • format (optional): Target format - "png", "jpeg", "jpg", "gif", "bmp", "tiff" (preserves original if not specified)

Usage Examples:

  1. Basic paste: paste_image

  2. Custom filename: paste_image({"filename": "screenshot"})

  3. Format conversion: paste_image({"format": "jpeg"})

  4. Both options: paste_image({"filename": "diagram", "format": "png"})

Returns:

  • Success: File path, format info, and size details

  • Error: Helpful troubleshooting information

🎯 Slash Commands

After running ./setup-claude-commands.sh, you can use these slash commands directly in Claude Code:

Command

Description

Usage

/pasteimage

Paste and analyze image

/pasteimage

/pasteimage --debug

Paste and debug errors

/pasteimage --debug

/pasteimage --explain

Paste and explain diagrams

/pasteimage --explain

/pi

Quick paste shortcut

/pi

/paste-debug

Paste and debug (alias)

/paste-debug

/paste-explain

Paste and explain (alias)

/paste-explain

Slash Command Examples:

/pasteimage                    → Paste image and analyze
/pasteimage --debug            → Paste image and debug error
/pi                           → Quick paste 
/paste-debug                  → Debug screenshot

Workflow

  1. Copy Image: Copy any image to clipboard (Ctrl+C/Cmd+C)

  2. Call Tool: Use paste_image tool in Claude Code

  3. Get Path: Receive temporary file path

  4. Process: Claude Code can now read and analyze the image

Error Handling

The server provides comprehensive error handling for:

  • No image in clipboard

  • Clipboard access permissions

  • Unsupported formats

  • File system errors

  • Platform compatibility issues

Security Considerations

  • Images are saved to system temporary directory

  • No network requests or external API calls

  • Temporary files use UUID naming to avoid conflicts

  • Cross-platform clipboard access uses standard system utilities

  • No persistent data storage

Platform Support

Platform

Primary Method

Fallback Method

Status

macOS

osascript

pngpaste

✅ Supported

Linux

xclip

wl-paste

✅ Supported

Windows

PowerShell

-

✅ Supported

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Start production server
npm start

Troubleshooting

Common Issues

  1. "No image found in clipboard"

    • Ensure an image is actually copied (not just selected)

    • Try copying the image again

    • Some applications may not properly set clipboard data

  2. Clipboard access errors

    • Check system permissions for clipboard access

    • Ensure required utilities are installed (xclip, wl-paste)

    • Try restarting the MCP server

  3. Platform-specific issues

    • Linux: Install xclip or wl-paste depending on display server

    • macOS: Consider installing pngpaste for better compatibility

    • Windows: Ensure PowerShell execution policy allows scripts

Debug Mode

Set environment variable for detailed logging:

DEBUG=1 node dist/index.js

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make changes with tests

  4. Submit a pull request

For bug reports and feature requests, please use the GitHub issues page.

Available Tools

4 tools
auto_paste_statusA

Check the current status of auto-paste detection (enabled/disabled).

Inputs: no named parameters.

disable_auto_pasteA

Disable automatic paste detection. Returns to manual paste mode using slash commands only.

Inputs: no named parameters.

enable_auto_pasteA

Enable automatic paste detection. When enabled, copying an image and pressing Ctrl+V will automatically trigger image pasting without needing to type slash commands.

Inputs: no named parameters.

paste_imageA

Paste an image from the system clipboard. Captures clipboard image data, saves it to a temporary file, and returns the file path for Claude Code to display. Supports common image formats (PNG, JPEG, GIF, BMP, TIFF).

Inputs: format, filename.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a singular purpose: paste_image performs the actual paste, while enable/disable/status manage the auto-paste setting. There is no overlap or ambiguity between the action-oriented and configuration-oriented tools.

    Naming Consistency4/5

    Most tools follow a clear verb_noun pattern (paste_image, enable_auto_paste, disable_auto_paste). The status tool uses a noun phrase (auto_paste_status) instead of a verb, which is a slight deviation, but the style is consistent and readable.

    Tool Count5/5

    Four tools is well-scoped for a clipboard-image server. The set covers the core function (pasting) plus the auto-paste feature without unnecessary bloat.

    Completeness5/5

    The tool surface fully covers the domain: manual paste, auto-paste enable/disable, and status query. There appear to be no missing operations or dead ends for a clipboard-image utility.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers