ClipToWSL MCP服务器
ClipToWSL是一个模型上下文协议（MCP）服务器，它使Claude Code等AI编码代理能够从WSL（Linux的Windows子系统）中读取Windows剪贴板内容。这允许在WSL环境中工作时无缝访问剪贴板数据，包括文本和图像。
快速开始：为了便于安装，请下载 发布包 其中包括预构建的二进制文件和自动设置脚本。
特性
- 跨平台剪贴板访问：从WSL读取Windows剪贴板
- 多种内容类型：支持文本和图像剪贴板数据
- Base64图像编码：图像的自动PNG转换和Base64编码
- MCP协议合规性：与Claude Code和其他MCP客户端完全集成
- 稳健的流程管理：具有健康检查的自动流程生命周期管理
- 错误处理：全面的错误处理和恢复机制
建筑
该系统由两个主要部分组成：
- Windows剪贴板阅读器 (
clipboard-reader/)：一个使用Win32 API访问Windows剪贴板的C++可执行文件 - MCP服务器 (
mcp-server/)：一个Types/Node.js服务器，管理Windows可执行文件并通过MCP协议公开剪贴板功能
组件之间的通信通过stdin/stdout管道使用JSON-RPC。
先决条件
开发/建筑：
- WSL（Linux的Windows子系统）
- 基于Ubuntu/Debian的WSL发行版
- 适用于Windows的MinGW-w64交叉编译器
- Node.js 18+
- TypeScript
使用方法：
- WSL环境
- Node.js 18+
- Claude Code或其他MCP兼容客户端
安装
选项1：快速安装（推荐）
下载 发布包 其中包括预构建的二进制文件：
# 1. Download and extract the release package
wget https://github.com/CarlosGtrz/ClipToWslMcp/releases/download/v1.0.0/clip-to-wsl-mcp-v1.0.0.zip
unzip clip-to-wsl-mcp-v1.0.0.zip
cd clip-to-wsl-mcp-v1.0.0/
# 2. Run the automated installer
./install.sh
# 3. Follow the configuration instructions printed by the installer安装程序将：
- 安装Node.js依赖项
- 设置可执行权限
- 生成Claude代码配置模板
- 提供设置的后续步骤
选项2：从源代码构建
对于开发或定制：
# 1. Clone the repository
git clone
cd ClipToWslMcp
# 2. Install build dependencies
sudo apt update
sudo apt install gcc-mingw-w64-x86-64-posix g++-mingw-w64-x86-64-posix
npm install -g typescript
# 3. Install Node.js dependencies
cd mcp-server && npm install && cd ..
# 4. Build the project
./create-release.sh # Creates optimized release build配置
Claude代码集成
将以下配置添加到您的Claude代码设置中：
Linux/WSL: ~/.claude.json
对于发布包安装：
{
"mcpServers": {
"clip-to-wsl": {
"command": "node",
"args": ["/path/to/release/index.js"],
"env": {
"CLIPBOARD_EXE_PATH": "/path/to/release/clipreader.exe"
}
}
}
}对于源代码构建安装：
{
"mcpServers": {
"clip-to-wsl": {
"command": "node",
"args": ["/full/path/to/ClipToWslMcp/mcp-server/dist/index.js"],
"env": {
"CLIPBOARD_EXE_PATH": "/full/path/to/ClipToWslMcp/clipboard-reader/clipreader.exe"
}
}
}
}重要：将路径替换为实际安装目录。自动安装程序创建 claude-config-example.json 使用正确的系统路径创建文件。
环境变量
CLIPBOARD_EXE_PATH：Windows剪贴板阅读器可执行文件的路径（必需）
用法
配置后 read_clipboard 工具将在Claude Code中可用：
文本剪贴板
当您将文本复制到Windows剪贴板时，您可以询问Claude Code：
- “我的剪贴板里有什么？”
- “读取剪贴板内容”
- “使用剪贴板中的文本”
图像剪贴板
当您复制图像（屏幕截图、复制的图像等）时，Claude Code可以：
- 查看和分析图像
- 描述图像中的内容
- 处理图像数据
刀具参数
这 read_clipboard 工具接受可选 format 参数：
"auto"（默认）：自动检测并返回最佳可用格式"text"：强制仅以文本形式阅读"image"：仅强制读取图像
测试
测试Windows可执行文件
cd clipboard-reader
echo '{"jsonrpc":"2.0","method":"read_clipboard","id":1}' | ./clipreader.exe测试MCP服务器
node test-server.js测试集成
cd mcp-server
npm start
# In another terminal, send MCP requests to test functionality故障排除
常见问题
- “找不到命令”错误
- 确保MinGW-w64安装正确： x86_64-w64-mingw32-g++ --version - 检查配置中的所有路径是否都是绝对路径
- 进程通信超时
- 验证可执行路径是否正确且可访问 - 检查Windows可执行文件是否具有适当的权限 - 确保可执行文件可以运行（直接执行测试）
- MCP工具未出现在Claude代码中
- 验证配置路径和语法 - 检查Claude Code日志中的MCP服务器启动错误 - 配置更改后重新启动Claude代码
- 剪贴板访问失败
- 确保您在WSL中运行时可以访问Windows剪贴板 - 检查Windows剪贴板是否包含数据 - 验证没有其他应用程序阻止剪贴板访问
调试命令
# Check if executable was built successfully
ls -la clipboard-reader/clipreader.exe
# Test executable directly
echo '{"method":"read_clipboard","id":1}' | /path/to/clipreader.exe
# Check MCP server startup
cd mcp-server && node dist/index.js
# Monitor process communication
ps aux | grep clipreader日志
MCP服务器提供用于调试的控制台日志记录：
- 流程启动和关闭事件
- 健康检查结果
- 错误消息和堆栈跟踪
- 请求/响应通信日志
发展
项目结构
ClipToWslMcp/
├── clipboard-reader/ # C++ Windows executable
│ ├── src/
│ │ ├── main.cpp # JSON-RPC communication
│ │ ├── clipboard.cpp # Windows clipboard access
│ │ ├── clipboard.h
│ │ ├── base64.cpp # Base64 encoding
│ │ └── base64.h
│ ├── Makefile # Build configuration with optimizations
│ └── clipreader.exe # Built executable (after build)
├── mcp-server/ # TypeScript MCP server
│ ├── src/
│ │ ├── index.ts # Main server
│ │ ├── clipboard-manager.ts # Process management
│ │ └── types.ts # Type definitions
│ ├── dist/ # Compiled JavaScript (after build)
│ ├── package.json
│ └── tsconfig.json
├── release/ # Ready-to-use release package
│ ├── index.js # Compiled MCP server
│ ├── clipreader.exe # Optimized Windows executable
│ ├── package.json # Runtime dependencies only
│ ├── install.sh # Automated installer
│ └── README.md # Installation instructions
├── create-release.sh # Automated release builder
├── shared/ # Shared configuration
│ └── config.json # Claude Code config template
└── docs/ # Documentation从源头构建
- 安装开发依赖项（MinGW-w64、Node.js、TypeScript）
- 使用MinGW-w64交叉编译Windows可执行文件
- 构建TypeScript MCP服务器
- 使用
./create-release.sh创建优化的发布包 - 测试组件之间的集成
创建发布包
自动发布构建器创建了一个分发就绪的包：
./create-release.sh此脚本：
- 通过大小优化构建优化的Windows可执行文件
- 将TypeScript编译为JavaScript
- 仅使用运行时依赖项创建发布包
- 生成安装脚本和文档
- 生成一个可供分发的独立软件包
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 彻底测试
- 提交拉取请求
安全考虑
- Windows可执行文件以最小权限运行
- 剪贴板数据在本地处理，无需网络传输
- 进程隔离防止访问敏感的WSL环境
- 输入验证可防止注入攻击
- 资源限制可防止内存耗尽
演出
- 内存使用：针对具有流式处理的大图像进行了优化
- 启动时间：流程重用最大限度地减少了初始化开销
- 图像处理：高效的PNG压缩和Base64编码
- 错误恢复：出现故障时自动重启进程
许可证
MIT许可证-有关详细信息，请参阅许可证文件。
支持
对于问题、错误报告或功能请求，请在存储库中创建问题。