MCP Clipboard Server

MCP剪贴板服务器

高性能、免锁 模型上下文协议（MCP） 为AI助手提供剪贴板访问的服务器。专为解决使用Claude时VSCode+WSL2图像剪贴板的限制而设计。

🎯 问题解决了

VSCode+WSL2+Claude图像剪贴板问题：在Windows上使用WSL2在VSCode中运行Claude时，由于沙盒环境，从剪贴板粘贴图像不起作用。此MCP服务器提供了一个从WSL2环境中访问Windows剪贴板内容（包括图像）的桥梁。

✨ 特性

• 🔒 无锁并行设计 -零竞争条件下的高性能
• 🖼️ 图像剪贴板支持 -PNG、JPEG、GIF、WebP、BMP检测和处理
• 🛡️ WSL2兼容性 -从WSL2无缝访问Windows剪贴板
• 📁 大型内容处理 -自动为大于25KB的内容创建临时文件
• 🔄 实时监控 -剪贴板更改通知
• 🧹 智能清理 -基于TTL的临时文件管理
• 🚀 无比赛条件 -全面的原子操作和CAS循环
• 🔍 丰富的调试 -详细的错误上下文和可选的调试日志记录

🚀 快速开始

NPM安装（推荐）

npm install -g @standardbeagle/mcp-clip

转到安装

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

手动安装

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桌面配置

添加到您的Claude桌面 claude_desktop_config.json:

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

配置文件位置：

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

🔧 VSCode+WSL2设置

1.安装在WSL2中

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

2.配置Claude代码扩展

添加到您的VSCode设置或工作区 .vscode/settings.json:

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

3.WSL2 PowerShell访问

确保PowerShell可从WSL2访问：

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

🛠️ 可用工具

read_clipboard

通过自动格式检测读取当前剪贴板内容。

Claude中的示例用法：

“阅读我的剪贴板并分析内容”

支持的格式：

• 纯文本
• 图像（PNG、JPEG、GIF、WebP、BMP）
• 二进制数据（base64编码）

大型内容处理：

• 25KB以上的内容自动保存到临时文件
• 图像始终保存为具有适当扩展名的文件
• 为外部访问提供的文件路径

📊 资源通知

当剪贴板内容发生变化时，服务器会发送实时通知：

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

这使Claude能够主动知道何时有新内容可用，而无需轮询。

⚙️ 配置

环境变量

• MCP_DEBUG=1 -启用详细的调试日志记录
• MCP_CLEANUP_TTL=2h -设置临时文件清理TTL（默认值：1h）

调试模式

MCP_DEBUG=1 mcp-clip

显示以下详细信息：

• 剪贴板监控状态
• 临时文件创建和清理
• WSL2 PowerShell集成
• 比赛条件倒退（极为罕见）

🧪 测试

试验装置

mcp-clip test

开发测试

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

# Build with race detector
go build -race .

🏗️ 建筑

免锁设计

• 原子操作 对于所有共享状态
• 比较和交换循环 有重试限制
• 零互斥 在炎热的道路上
• 无比赛条件 在所有负载下

并发安全

• 原子剪贴板状态更新
• 线程安全会话文件跟踪
• 优雅的关机和清理
• TOCTU安全临时文件创建

平台集成

• WSL2：用于Windows剪贴板的PowerShell桥
• Linux：通过atotto/剪贴板直接集成剪贴板
• macOS：原生剪贴板支持
• 视窗：原生剪贴板支持

🔧 故障排除

WSL2问题

未找到PowerShell：

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

权限被拒绝：

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

WSL2中的剪贴板为空：

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

一般问题

MCP连接失败：

• 验证 mcp-clip 在你的路径中
• 检查Claude Desktop配置JSON语法
• 配置更改后重新启动Claude Desktop

大图像无法正常工作：

• 检查临时目录中的可用磁盘空间
• 验证临时目录权限
• 启用调试模式： MCP_DEBUG=1

性能问题：

• 启用调试模式的监视器
• 检查防病毒干扰
• 验证WSL2资源分配

📝 发展

从源头构建

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

运行测试

go test -race -v ./...

贡献

1. 分叉存储库
2. 创建要素分支
3. 运行测试： go test -race -v ./...
4. 提交拉取请求

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 模型上下文协议 通过Anthropic
• atotto/剪贴板 用于跨平台剪贴板访问
• mcp走 用于Go MCP实施

🔗 链接

• 模型上下文协议
• 克劳德桌面