ClipToWSL MCP 服务器

ClipToWSL 是一个模型上下文协议（MCP）服务器，它使像 Claude Code 这样的AI编码代理能够在 Windows 子系统 for Linux (WSL) 中读取 Windows 剪贴板的内容。这使得在 WSL 环境中工作时能够无缝访问剪贴板数据，包括文本和图像。

快速开始：为了方便安装，请下载发行包，其中包含了预编译的二进制文件和自动安装脚本。

功能

• 跨平台剪贴板访问：从 WSL 访问 Windows 剪贴板
• 多种内容类型支持：支持文本和图像剪贴板数据
• Base64 图像编码：自动将 PNG 转换并进行 Base64 编码
• 符合 MCP 协议：与 Claude Code 和其他 MCP 客户端完全集成
• 强大的进程管理：带有健康检查的自动进程生命周期管理
• 错误处理：全面的错误处理和恢复机制

架构

该系统由两个主要组件组成：

1. Windows 剪贴板阅读器 (clipboard-reader/)：一个使用 Win32 API 访问 Windows 剪贴板的 C++ 可执行文件
2. MCP 服务器 (mcp-server/)：一个 TypeScript/Node.js 服务器，用于管理 Windows 可执行文件并通过 MCP 协议提供剪贴板功能

组件之间的通信通过 stdin/stdout 管道使用 JSON-RPC 进行。

先决条件

开发/构建：

• WSL（Windows 子系统 for Linux）
• 基于 Ubuntu/Debian 的 WSL 发行版
• MinGW-w64 Windows 跨编译器
• Node.js 18+
• TypeScript

使用：

• WSL 环境
• Node.js 18+
• Claude Code 或其他兼容 MCP 的客户端

安装

方案 1：快速安装（推荐）

下载包含预编译二进制文件的发行包：

# 1. 下载并解压发行包
wget https://github.com/CarlosGtrz/ClipToWslMcp/releases/download/v1.0.0/clip-to-wsl-mcp-v1.0..zip
unzip clip-to-wsl-mcp-v1.0.0.zip
cd clip-to-wsl-mcp-v1.0.0/

# 2. 运行自动安装程序
./install.sh

# 3. 按照安装程序打印的配置说明操作

安装程序将：

• 安装 Node.js 依赖项
• 设置可执行权限
• 生成 Claude Code 配置模板
• 提供下一步设置说明

方案 2：从源代码构建

用于开发或定制：

# 1. 克隆仓库
git clone <repository-url>
cd ClipToWslMcp

# 2. 安装构建依赖项
sudo apt update
sudo apt install gcc-mingw-w64-x86-64-posix g++-mingw-w64-x86-64-posix
npm install -g typescript

# 3. 安装 Node.js 依赖项
cd mcp-server && npm install && cd ..

# 4. 构建项目
./create-release.sh  # 创建优化的发布构建

配置

Claude Code 集成

在您的 Claude Code 设置中添加以下配置：

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
# 在另一个终端发送 MCP 请求以测试功能

故障排除

常见问题

1. “命令未找到”错误

   • 确保 MinGW-w64 正确安装：x86_64-w64-mingw32-g++ --version
   • 检查配置中的所有路径是否为绝对路径

2. 进程通信超时

   • 验证可执行路径正确且可访问
   • 检查 Windows 可执行文件是否有适当的权限
   • 确保可执行文件可以运行（直接执行测试）

3. MCP 工具未出现在 Claude Code 中

   • 验证配置路径和语法
   • 检查 Claude Code 日志中的 MCP 服务器启动错误
   • 配置更改后重启 Claude Code

4. 剪贴板访问失败

   • 确保您正在从具有访问 Windows 剪贴板权限的 WSL 中运行
   • 检查 Windows 剪贴板是否包含数据
   • 确认没有其他应用程序阻止剪贴板访问

调试命令

# 检查可执行文件是否成功构建
ls -la clipboard-reader/clipreader.exe

# 直接测试可执行文件
echo '{"method":"read_clipboard","id":1}' | /path/to/clipreader.exe

# 检查 MCP 服务器启动
cd mcp-server && node dist/index.js

# 监控进程通信
ps aux | grep clipreader

日志

MCP 服务器提供了调试用的控制台日志：

• 进程启动和关闭事件
• 健康检查结果
• 错误消息和堆栈跟踪
• 请求/响应通信日志

开发

项目结构

ClipToWslMcp/
├── clipboard-reader/        # C++ Windows 可执行文件
│   ├── src/
│   │   ├── main.cpp        # JSON-RPC 通信
│   │   ├── clipboard.cpp   # Windows 剪贴板访问
│   │   ├── clipboard.h
│   │   ├── base64.cpp      # Base64 编码
│   │   └── base64.h
│   ├── Makefile            # 带有优化的构建配置
│   └── clipreader.exe      # 构建后的可执行文件
├── mcp-server/             # TypeScript MCP 服务器
│   ├── src/
│   │   ├── index.ts        # 主服务器
│   │   ├── clipboard-manager.ts  # 进程管理
│   │   └── types.ts        # 类型定义
│   ├── dist/               # 构建后的 JavaScript
│   ├── package.json
│   └── tsconfig.json
├── release/                # 准备使用的发行包
│   ├── index.js           # 构建后的 MCP 服务器
│   ├── clipreader.exe     # 优化后的 Windows 可执行文件
│   ├── package.json       # 运行时依赖项
│   ├── install.sh         # 自动安装程序
│   └── README.md          # 安装说明
├── create-release.sh       # 自动化发行包构建器
├── shared/                 # 共享配置
│   └── config.json         # Claude Code 配置模板
└── docs/                   # 文档

从源代码构建

1. 安装开发依赖项（MinGW-w64，Node.js，TypeScript）
2. 使用 MinGW-w64 跨编译 Windows 可执行文件
3. 构建 TypeScript MCP 服务器
4. 使用 ./create-release.sh 创建优化的发行包
5. 测试组件间的集成

创建发行包

自动化发行包构建器创建了一个准备分发的包：

./create-release.sh

此脚本：

• 构建了带有大小优化的 Windows 可执行文件
• 将 TypeScript 编译为 JavaScript
• 创建了只包含运行时依赖项的发行包
• 生成了安装脚本和文档
• 生产了一个独立的分发包

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

安全考虑

• Windows 可执行文件以最小权限运行
• 剪贴板数据本地处理，不进行网络传输
• 进程隔离防止访问敏感的 WSL 环境
• 输入验证防止注入攻击
• 资源限制防止内存耗尽

性能

• 内存使用：针对大型图像进行了流处理优化
• 启动时间：进程复用最小化初始化开销
• 图像处理：高效的 PNG 压缩和 Base64 编码
• 错误恢复：故障时自动重启进程

许可证

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

支持

对于问题、错误报告或功能请求，请在仓库中创建一个 Issue。 </中文翻译>