AI导哈

剪贴板服务

一个为AI助手如Claude提供系统剪贴板读写功能的Model Context Protocol (MCP)服务器。

  • by gabiteodoru
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 gabiteodoru/clipboard-mcp

使用说明

剪贴板MCP服务器

一个模型上下文协议（MCP）服务器，为像Claude这样的AI助手提供系统剪贴板的读写功能。

⚠️ 重要提示：请先安装系统依赖

Linux用户在使用此软件包之前必须安装剪贴板实用程序：

# For X11 (most common)
sudo apt install xclip xsel

# For Wayland
sudo apt install wl-clipboard

# Other distributions
sudo dnf install xclip xsel      # Fedora/RHEL
sudo pacman -S xclip xsel         # Arch Linux

WSL 用户： 通常情况下，它开箱即用，利用Windows剪贴板工具即可。如果您遇到问题，请安装 xclip xsel 如上所述。

macOS和Windows用户： 无需额外依赖！

特点/特性

  • 读取剪贴板从系统剪贴板读取文本内容
  • 将内容写入剪贴板将文本内容写入系统剪贴板
  • 跨平台支持（Linux、macOS、Windows、WSL）
  • 轻量级，依赖极少

安装

选项1：pip（推荐）

pip install clipboard-mcp

考虑使用虚拟环境以避免依赖冲突：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install clipboard-mcp

选项2：uv（轻量级，适合尝试使用）

直接使用 uv 运行（无需 pip 安装）：

# One-time execution
uv run --from clipboard-mcp clipboard-mcp

# Or clone and run from source
git clone https://github.com/gabiteodoru/clipboard-mcp.git
cd clipboard-mcp
uv run clipboard-mcp

选项3：来自源

git clone https://github.com/gabiteodoru/clipboard-mcp.git
cd clipboard-mcp
pip install -e .

使用方法

使用 Claude CLI

安装pip之后：

claude mcp add --scope user clipboard-mcp clipboard-mcp

带有紫外线（无需安装）：

claude mcp add --scope user clipboard-mcp "uv run --from clipboard-mcp clipboard-mcp"

或者从源目录中：

claude mcp add --scope user clipboard-mcp "uv run /path/to/clipboard-mcp"

使用Claude Desktop

添加到您的Claude桌面配置文件中。

配置文件位置：

  • macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows： %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

安装pip之后：

{
  "mcpServers": {
    "clipboard": {
      "command": "clipboard-mcp"
    }
  }
}

使用紫外线（无需安装）：

{
  "mcpServers": {
    "clipboard": {
      "command": "uv",
      "args": [
        "run",
        "--from",
        "clipboard-mcp",
        "clipboard-mcp"
      ]
    }
  }
}

来自源目录：

{
  "mcpServers": {
    "clipboard": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/clipboard-mcp",
        "run",
        "clipboard-mcp"
      ]
    }
  }
}

可用工具

一旦配置完成，Claude将能够使用这些工具：

  • `read_clipboard()` 翻译成中文是“从剪贴板读取” - 读取当前剪贴板内容
  • 将文本写入剪贴板 - 将文本写入剪贴板

示例交互

有了这个MCP服务器运行，你可以让Claude做到：

  • “读取我剪贴板中的内容”
  • “将这段代码复制到我的剪贴板”
  • “将此输出保存到我的剪贴板，以便我可以在其他地方粘贴。”

它是如何运作的

这个MCP服务器使用的是 pyperclip（这个词汇本身在中文中没有直接对应的翻译，它是一个Python库的名称，用于复制和粘贴剪贴板内容，可以简单理解为“剪贴板操作库”或保持原样使用“pyperclip”） 一个用于与系统剪贴板交互的库。它通过模型上下文协议在Claude和您的剪贴板之间提供了一个安全的桥梁。

故障排除

Linux：“无法读取剪贴板”错误

问题缺少系统剪贴板实用程序

解决方案安装所需的工具：

# For X11
sudo apt install xclip xsel

# For Wayland
sudo apt install wl-clipboard

# Or use PyQt5 as fallback (larger dependency)
pip install PyQt5

Linux：在无头环境中运行

问题没有可用的显示服务器（例如，SSH 会话、Docker）

解决方案剪贴板操作需要显示服务器。对于无头环境，请考虑：

  • 使用X11转发： ssh -X user@host
  • 使用Xvfb运行虚拟显示器
  • 使用替代的数据传输方法

验证

手动测试安装：

# Test reading clipboard (copy something first)
python -c "import pyperclip; print(pyperclip.paste())"

# Test writing to clipboard
python -c "import pyperclip; pyperclip.copy('Hello from Python')"

寻求帮助

如果您遇到问题：

  1. 检查您的平台是否已安装所需的依赖项
  2. 验证pyperclip能否独立工作（参见上述验证）
  3. 打开一个问题（或议题） 包含有关您平台的详细信息和错误消息

要求

平台特定要求

平台 要求 状态
macOS 内置（pbcopy/pbpaste） ✅ 无需设置
Windows 内置（clip.exe，PowerShell） ✅ 无需安装
Linux X11 xclip 或 xsel ⚠️ 需手动安装
Linux Wayland wl-clipboard ⚠️ 需要手动安装
WSL Windows 剪贴板工具 ✅ 通常预装

安全与隐私

  • 此服务器仅在Claude明确请求时才访问剪贴板内容
  • 除非您要求Claude读取/写入，否则不会存储或传输任何剪贴板数据
  • 所有操作都在您的本地机器上进行

许可证

麻省理工学院（MIT）

做出贡献

欢迎贡献！请随时提交拉取请求。

链接

相关 MCP