@standardbeagle/mcp-clip

MCP Clipboard Server

A high-performance, lock-free Model Context Protocol (MCP) server that provides clipboard access for AI assistants. Specifically designed to solve the VSCode + WSL2 image clipboard limitation when using Claude.

🎯 Problem Solved

VSCode + WSL2 + Claude Image Clipboard Issue: When running Claude in VSCode on Windows with WSL2, pasting images from the clipboard doesn't work due to the sandboxed environment. This MCP server provides a bridge to access Windows clipboard content (including images) from within the WSL2 environment.

✨ Features

• 🔒 Lock-free concurrent design - High performance with zero race conditions
• 🖼️ Image clipboard support - PNG, JPEG, GIF, WebP, BMP detection and handling
• 🛡️ WSL2 compatibility - Seamless Windows clipboard access from WSL2
• 📁 Large content handling - Automatic temp file creation for content >25KB
• 🔄 Real-time monitoring - Clipboard change notifications
• 🧹 Smart cleanup - TTL-based temp file management
• 🚀 Race condition free - Comprehensive atomic operations and CAS loops
• 🔍 Rich debugging - Detailed error context and optional debug logging

🚀 Quick Start

NPM Installation (Recommended)

npm install -g @standardbeagle/mcp-clip

Go Installation

go install github.com/standardbeagle/mcp-clip@latest

Manual Installation

git clone https://github.com/standardbeagle/mcp-clip.git
cd mcp-clip
go build -o mcp-clip
sudo cp mcp-clip /usr/local/bin/

📋 Claude Desktop Configuration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "clipboard": {
      "command": "mcp-clip",
      "args": []
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

🔧 VSCode + WSL2 Setup

1. Install in WSL2

# In your WSL2 terminal
npm install -g @standardbeagle/mcp-clip

2. Configure Claude Code Extension

Add to your VSCode settings or workspace .vscode/settings.json:

{
  "claude-dev.mcpServers": {
    "clipboard": {
      "command": "mcp-clip",
      "args": []
    }
  }
}

3. WSL2 PowerShell Access

Ensure PowerShell is accessible from WSL2:

# Test PowerShell access
/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -Command "Get-Clipboard"

🛠️ Available Tools

read_clipboard

Reads current clipboard content with automatic format detection.

Example usage in Claude:

"Read my clipboard and analyze the content"

Supported formats:

• Plain text
• Images (PNG, JPEG, GIF, WebP, BMP)
• Binary data (base64 encoded)

Large content handling:

• Content >25KB automatically saved to temp files
• Images always saved as files with proper extensions
• File paths provided for external access

📊 Resource Notifications

The server sends real-time notifications when clipboard content changes:

{
  "method": "notifications/resources/updated",
  "params": {
    "uri": "clipboard://current"
  }
}

This allows Claude to proactively know when new content is available without polling.

⚙️ Configuration

Environment Variables

• MCP_DEBUG=1 - Enable detailed debug logging
• MCP_CLEANUP_TTL=2h - Set temp file cleanup TTL (default: 1h)

Debug Mode

MCP_DEBUG=1 mcp-clip

Shows detailed information about:

• Clipboard monitoring status
• Temp file creation and cleanup
• WSL2 PowerShell integration
• Race condition fallbacks (extremely rare)

🧪 Testing

Test Installation

mcp-clip test

Development Testing

# Run tests with race detector
go test -race -v ./...

# Build with race detector
go build -race .

🏗️ Architecture

Lock-Free Design

• Atomic operations for all shared state
• Compare-and-swap loops with retry limits
• Zero mutexes in hot paths
• Race-condition free under all loads

Concurrency Safety

• Atomic clipboard state updates
• Thread-safe session file tracking
• Graceful shutdown with cleanup
• TOCTOU-safe temp file creation

Platform Integration

• WSL2: PowerShell bridge for Windows clipboard
• Linux: Direct clipboard integration via atotto/clipboard
• macOS: Native clipboard support
• Windows: Native clipboard support

🔧 Troubleshooting

WSL2 Issues

PowerShell not found:

# Install Windows PowerShell in WSL2
sudo apt update && sudo apt install powershell

Permission denied:

# Add Windows PowerShell to PATH
echo 'export PATH="/mnt/c/Windows/System32/WindowsPowerShell/v1.0:$PATH"' >> ~/.bashrc
source ~/.bashrc

Clipboard empty in WSL2:

# Test Windows clipboard access
powershell.exe "Get-Clipboard" 

General Issues

MCP connection failed:

• Verify mcp-clip is in your PATH
• Check Claude Desktop config JSON syntax
• Restart Claude Desktop after config changes

Large images not working:

• Check available disk space in temp directory
• Verify temp directory permissions
• Enable debug mode: MCP_DEBUG=1

Performance issues:

• Monitor with debug mode enabled
• Check for antivirus interference
• Verify WSL2 resource allocation

📝 Development

Building from Source

git clone https://github.com/standardbeagle/mcp-clip.git
cd mcp-clip
go mod download
go build -race .

Running Tests

go test -race -v ./...

Contributing

• Fork the repository
• Create a feature branch
• Run tests: go test -race -v ./...
• Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• atotto/clipboard for cross-platform clipboard access
• mcp-go for Go MCP implementation

🔗 Links

• GitHub Repository
• NPM Package
• Model Context Protocol
• Claude Desktop