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.

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:

Method A: Project-scoped (Recommended)

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:

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

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.