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

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:

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.