剪切板服务

Name: 剪切板服务
Author: standardbeagle

作者：standardbeagle4 星标更新：2025-07-06

安装使用来源：spider==github.com

项目介绍

MCP剪贴板服务器

一个高性能、无锁的模型上下文协议（MCP）服务器，提供AI助手的剪贴板访问。特别设计用于解决在使用Claude时，VSCode与WSL2环境中的图像剪贴板限制问题。

🎯 解决的问题

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

✨ 特性

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

🚀 快速开始

NPM安装（推荐）

npm install -g @standardbeagle/mcp-clip

Go安装

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
Windows：%APPDATA%\Claude\claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

🔧 VSCode + WSL2设置

1. 在WSL2中安装

# 在你的WSL2终端中
npm install -g @standardbeagle/mcp-clip

2. 配置Claude代码扩展

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

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

3. WSL2 PowerShell访问

确保可以从WSL2访问PowerShell：

# 测试PowerShell访问
/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（默认：1小时）

调试模式

MCP_DEBUG=1 mcp-clip

显示关于以下方面的详细信息：

剪贴板监控状态
临时文件的创建和清理
WSL2 PowerShell集成
竞态条件回退（极其罕见）

🧪 测试

测试安装

mcp-clip test

开发测试

# 使用竞态检测器运行测试
go test -race -v ./...

# 使用竞态检测器构建
go build -race .

🏗️ 架构

无锁设计

所有共享状态的原子操作
带重试限制的比较和交换循环
热点路径中零互斥量
在所有负载下无竞态条件

并发安全性

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

平台集成

WSL2：通过PowerShell桥接访问Windows剪贴板
Linux：通过atotto/clipboard直接集成剪贴板
macOS：原生剪贴板支持
Windows：原生剪贴板支持

🔧 故障排除

WSL2问题

未找到PowerShell：

# 在WSL2中安装Windows PowerShell
sudo apt update && sudo apt install powershell

权限被拒绝：

# 将Windows PowerShell添加到PATH
echo 'export PATH="/mnt/c/Windows/System32/WindowsPowerShell/v1.0:$PATH"' >> ~/.bashrc
source ~/.bashrc

WSL2中剪贴板为空：

# 测试Windows剪贴板访问
powershell.exe "Get-Clipboard"

一般问题

MCP连接失败：

验证mcp-clip是否在您的PATH中
检查Claude桌面配置JSON语法
在更改配置后重启Claude桌面

大型图像无法工作：

检查临时目录中的可用磁盘空间
验证临时目录权限
启用调试模式：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 ./...

贡献

分叉仓库
创建功能分支
运行测试：go test -race -v ./...
提交拉取请求

📄 许可证

MIT许可证 - 详情见LICENSE文件。

🙏 致谢

模型上下文协议由Anthropic提供
atotto/clipboard用于跨平台剪贴板访问
mcp-go用于Go MCP实现