Clip To Wsl MCP

ClipToWSL MCP服务器

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

快速开始：为了便于安装，请下载 发布包 其中包括预构建的二进制文件和自动设置脚本。

特性

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

建筑

该系统由两个主要部分组成：

1. Windows剪贴板阅读器 (clipboard-reader/)：一个使用Win32 API访问Windows剪贴板的C++可执行文件
2. 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

故障排除

常见问题

1. “找不到命令”错误

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

1. 进程通信超时

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

1. MCP工具未出现在Claude代码中

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

1. 剪贴板访问失败

- 确保您在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

从源头构建

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许可证-有关详细信息，请参阅许可证文件。

支持

对于问题、错误报告或功能请求，请在存储库中创建问题。