Submit
standardbeagle

MCP Clipboard Server

Community standardbeagle
Updated

High-performance MCP server for clipboard access with WSL2 support

MCP Clipboard Server

Go VersionLicense: MITMCP Compatible

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

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

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

🔗 Links

MCP Server · Populars

MCP Server · New