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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

A high-performance server that provides clipboard access for AI assistants, specifically designed to solve the VSCode + WSL2 image clipboard limitation when using Claude.

Related MCP Servers

MacOS Clipboard MCP Server
newbeb
A
security
A
license
A
quality
Provides AI assistants access to the macOS clipboard content, supporting text, images, and binary data via OSAScript.
Last updated -
1
2
TypeScript
MIT License
MCP Unified Server
getfounded
-
security
A
license
-
quality
A modular server implementation for Claude AI assistants with integrated tools, enabling Claude to perform actions and access external resources like file systems, web searches, browser automation, financial data, and document generation.
Last updated -
66
Python
MIT License
LPS MCPofficial
lpsDevelopers
-
security
A
license
-
quality
A minimal server that provides Claude AI with secure file system access and sequential thinking capabilities, allowing Claude to navigate directories, read files, and break down complex problems into structured thinking steps.
Last updated -
1
Python
MIT License
MCP Server
tcpipuk
-
security
A
license
-
quality
A server that enables AI assistants like Claude to safely run Python code and access websites, processing data for better AI understanding while providing helpful error messages.
Last updated -
2
Python
GPL 3.0

View all related MCP servers