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