Clipboard

mcp-clipboard

一个 MCP 服务，可让你的 AI 助手直接访问系统剪贴板：读取你复制的内容，或将纯净文本直接写入剪贴板。兼容任何支持 MCP 的客户端，包括 Claude Code、Claude Desktop、Cursor、Windsurf 等。

为什么需要它

粘贴会丢失结构

从 Google Sheets 或 Excel 复制单元格并粘贴到聊天输入框时，表格结构（行和列）会被破坏。内容会变成一串没有分隔符的纯文本。模型只能猜测一个单元格在哪里结束、下一个单元格在哪里开始，而且经常猜错。

mcp-clipboard 会保留表格结构。 不要粘贴，而是告诉助手“读取我的剪贴板”。服务会直接读取剪贴板，从电子表格应用放入剪贴板的 HTML 中识别表格数据，并将其作为格式规范的 Markdown 表格、JSON 或 CSV 返回。结构不会丢失，也无需猜测。

额外好处：还能解决从 Claude Code 复制内容的问题

Claude Code 的终端渲染器会为所有输出添加 2 个字符的边距、在约 80 列处强制换行，并留下尾随空白。从终端中选择并复制文本时，这些问题也会一并带上：

  echo "this is a long command that wraps and
  breaks when you paste it because of the hard
  newlines and leading spaces"

Claude Code 仓库中反复有人报告此问题（issues #4686、#6827、#7670、#13378、#15199、#25040、#25427、#26016），已有数十人点赞，但尚未发布修复。

mcp-clipboard 可以彻底绕过这个问题。 不要从终端复制文本，而是让 Claude Code 将内容放到剪贴板：

“把那条命令复制到我的剪贴板”

Claude Code 会调用 clipboard_copy，将干净的文本直接写入系统剪贴板，然后你就可以在需要的地方粘贴。没有多余边距、强制换行，也无需清理。

提示： 要让此操作自动进行，请在项目级或全局的 CLAUDE.md 中添加一行：

When you produce a shell command for the user to run, also copy it to the clipboard using clipboard_copy.

之后，Claude Code 每次建议命令时都会自动复制，无需你开口要求。

额外好处：无需按 Ctrl-C 即可读取 X11/Wayland 选区

Linux 桌面有两个剪贴板：Ctrl-C / Ctrl-V 使用的 CLIPBOARD，以及 PRIMARY 选区。PRIMARY 是你当前高亮选中的文本，通过鼠标中键粘贴。选中文本后它会立即更新；你无需复制。

mcp-clipboard 也能读取 PRIMARY。向 clipboard_paste、clipboard_read_raw 或 clipboard_list_formats 传入 selection="primary"，服务就会读取选区缓冲区，而不是 Ctrl-C 剪贴板。以下是一些可实现的工作流：

• 终端排查。 错误消息滚过时，用鼠标选中它，然后询问模型这是什么意思。Ctrl-C 缓冲区中的内容不会受到影响。
• vim / IDE 可视选择。 使用 v 选择一个函数，让模型解释或重构它。
• 浏览器 / PDF 阅读。 拖动鼠标选中一段文字，然后直接询问“这段在说什么？”，无需中断阅读流程。
• 双缓冲区工作流。 在 CLIPBOARD（Ctrl-C）中保留一段代码，并在同一对话中通过 PRIMARY 读取另一段代码。

仅限 Linux。macOS 和 Windows 没有对应的缓冲区；在这些平台上传入 selection="primary" 会返回明确的错误。

工具

工具	描述
clipboard_paste	**主要工具。**读取剪贴板中的任意内容：表格、文本、代码、JSON、URL、图像。表格会格式化为 Markdown/JSON/CSV；传入 include_schema=true 可附加推断出的列类型。图像会作为模型可查看的图像内容返回。可选参数 selection="primary" 用于读取 X11/Wayland PRIMARY 选区（中键单击／选择文本后粘贴的缓冲区），而不是默认的 Ctrl-C 剪贴板。
clipboard_copy	将文本内容写入系统剪贴板。接受可选的 mime_type 参数（默认为 text/plain；也支持 text/html、text/rtf、image/svg+xml，或 Wayland/X11 上的任意 text/*）。
clipboard_copy_markdown	将 markdown 渲染为 HTML，并把两种格式都放入剪贴板，让粘贴目标选择合适的格式——Slack/Gmail/Notion/Discord 会获得富文本；vim/终端会获得源文本。macOS/Windows 会以原子方式写入两种格式；Wayland/X11 只支持单 MIME，因此只写入 text/html。
clipboard_copy_image	根据 base64 编码的字节，将 PNG 或 JPEG 图像写入系统剪贴板。直接传递，不重新编码；会根据声明的 MIME 验证魔数。文本请使用 clipboard_copy。接受 selection="primary" 参数以使用 X11/Wayland PRIMARY 选区。
clipboard_list_formats	列出剪贴板当前包含的 MIME 类型。接受 selection="primary" 参数以使用 X11/Wayland PRIMARY 选区。
clipboard_read_raw	返回指定 MIME 类型的原始剪贴板内容（用于诊断）。任何非二进制类型都会直接传递；仅拒绝 image/*、audio/*、video/* 和 application/octet-stream。图像请使用 clipboard_paste。接受 selection="primary" 参数以使用 X11/Wayland PRIMARY 选区。
clipboard_version	返回正在运行的 mcp-clipboard 软件包版本，格式为 {"name": "mcp-clipboard", "version": "<x.y.z>"}。用于诊断。适用于不会向模型提供标准 MCP serverInfo 区块的宿主，也适用于需要记录某次运行所用构建版本的测试框架。

设置

步骤 1：安装 Python 软件包运行器

mcp-clipboard 是 PyPI 上的 Python 软件包。任何能够安装并启动控制台脚本入口点的 Python 工具，都可以用来将其作为 MCP 服务运行。最常见的两种选择是 pipx 和 uv；它们都显示在本 README 顶部的安装数量徽章中，也都在积极使用。请选择你已有或偏好的工具：

• pipx：各平台的安装说明见 pipx 官方安装文档。在大多数发行版中，可以通过系统软件包管理器（apt、dnf、pacman、brew 等）获取 pipx。
• uv：各平台的安装说明见 uv 官方安装文档。Astral 提供了软件包管理器安装方式、带签名的独立二进制文件下载，以及适用于各平台的 Shell 安装程序。

确认所选运行器位于 PATH 中：

pipx --version   # if you chose pipx

uv --version     # if you chose uv

本节其余部分会分别展示两种运行器的命令；请替换为你安装的运行器。

Step 2: 安装平台剪贴板工具（仅限 Linux）

macOS 和 Windows 已内置所需功能。Linux 需要一个 CLI 工具：

平台	工具	安装
Fedora / RHEL（Wayland）	wl-copy / wl-paste	sudo dnf install wl-clipboard
Ubuntu / Debian（Wayland）	wl-copy / wl-paste	sudo apt install wl-clipboard
Linux（X11）	xclip	sudo dnf install xclip 或 sudo apt install xclip
macOS	内置	无需安装（pbcopy / pbpaste）
Windows	内置	无需安装（PowerShell）

平台状态： Linux 上的 Wayland 已经过测试并投入实际使用。我们已在 QEMU Windows 客户机上对 Windows 进行了端到端测试（测试过程中发现并修复了一个仅影响 Windows 的真实编码错误，#129，修复见 v2.5.x）。X11 和 macOS 的实现已完成，但除单元测试外尚未验证。欢迎提交错误报告和 PR。

Step 3: 验证 mcp-clipboard 是否能在你的系统上正常运行

将其接入客户端之前，请确认软件包已安装，并能正确检测你的平台。使用 pipx：

pipx run mcp-clipboard --check

或者使用 uv：

uvx mcp-clipboard --check

这两种方式都会按需获取软件包，无需永久安装（如果你更希望永久安装，请先运行 pipx install mcp-clipboard 或 uv tool install mcp-clipboard）。预期输出：

mcp-clipboard 2.5.1
Platform: ...
Backend: ... (detected)
OK: mcp-clipboard should work on this system.

如果看到 Backend: NOT AVAILABLE，请按照错误消息中的平台专属提示操作（通常是安装 Step 2 中的 Linux 剪贴板工具），然后重新运行。

Step 4: 将服务注册到你的 MCP 客户端

MCP 主机通过 command + args 组合启动 mcp-clipboard。pipx 和 uv 都提供了一次性运行子命令，可获取并执行软件包，因此使用这些命令形式的配置最方便。

Claude Code

使用 pipx：

claude mcp add clipboard --scope user -- pipx run mcp-clipboard

使用 uv：

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

Claude Desktop

找到 Claude Desktop 配置文件（将路径粘贴到文件管理器的地址栏，即可直接跳转）：

• Linux： ~/.config/Claude/claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

在 mcpServers 中添加一个条目，使用以下任一种形式。使用 pipx：

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

或者使用 uv：

{
  "mcpServers": {
    "clipboard": {
      "command": "uvx",
      "args": ["mcp-clipboard"]
    }
  }
}

保存文件，然后完全退出并重新启动 Claude Desktop，以加载新服务。

Windows 提示： Claude Desktop 会缓存启动时的环境（包括 PATH）。如果在启动 Claude Desktop 后才安装 pipx/uvx，Claude Desktop 需要重启才能识别它们。如果上面的代码片段导致“Server failed to start”或 MCP 日志中出现类似“command not found”的错误，请右键单击 Claude Desktop 托盘图标，选择退出，然后重新打开 Claude Desktop。单击任务栏上的 X 只会隐藏窗口，缓存的环境仍然存在。

其他 MCP 客户端

任何支持 MCP stdio 服务的客户端都可以使用 mcp-clipboard。常见的一次性运行命令有 pipx run mcp-clipboard 和 uvx mcp-clipboard；如果你已永久安装 mcp-clipboard（pipx install mcp-clipboard 或 uv tool install mcp-clipboard），那么生成的 PATH 上的 mcp-clipboard 二进制文件也可以用作 command。请查阅客户端文档，了解如何注册 MCP 服务。

Step 5: 确认端到端运行正常

在客户端中询问：

我的剪贴板上有什么？

客户端应调用 clipboard_paste 并返回内容。如果你之前复制了电子表格选区或 URL，内容会以恰当的格式显示。

如果没有任何反应，或出现工具错误，请重新运行 --check（使用 Step 3 中的运行方式），确认软件包安装正常，然后检查客户端的 MCP 服务日志（各 MCP 主机查看日志的方式不同；请查阅客户端文档）。

升级

持久安装不会自动更新，而且如果存在通过 uv tool install 安装的副本，运行 uvx mcp-clipboard 时会使用该副本，而不是获取更新的版本。请显式升级：

uv tool upgrade mcp-clipboard   # if you used uv tool install
pipx upgrade mcp-clipboard      # if you used pipx install

一次性运行器也可能复用缓存的副本。uvx mcp-clipboard@latest 和 pipx run --no-cache mcp-clipboard 会强制重新检查。运行 --version 确认当前使用的版本，然后重启 MCP 客户端，使其启动新版本。

从源代码安装

如果你更喜欢本地克隆，而不是从 PyPI 安装：

git clone https://github.com/cmeans/mcp-clipboard.git
cd mcp-clipboard
uv sync

然后将客户端指向本地安装：

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

环境变量

可以通过配置中的 "env" 键传入环境变量。

变量	平台	用途	默认值
MCP_CLIPBOARD_DEBUG	所有平台	启用调试日志（设为 1 即可启用）	关闭
WAYLAND_DISPLAY	Linux（Wayland）	合成器套接字名称或绝对路径	自动检测
XDG_RUNTIME_DIR	Linux（Wayland）	包含 Wayland 套接字的目录	/run/user/<uid>
XDG_SESSION_TYPE	Linux	会话类型提示（wayland 或 x11）	通过扫描套接字自动检测

大多数 Linux 用户无需设置这些变量。若自动检测失败（存在多个合成器、套接字路径非标准，或处于容器化环境中），可进行覆盖。

使用方法

读取剪贴板

复制任意内容（电子表格单元格、代码、文本、URL、JSON、图像），然后：

• “粘贴我的剪贴板内容”
• “读取我的剪贴板”
• “我的剪贴板里有什么？”
• “我复制了一些数据，看看内容”

助手会调用 clipboard_paste，并在保留结构的同时返回内容。

写入剪贴板

当 Agent 生成你需要在其他地方使用的命令、代码块或任意文本时：

• “把它复制到我的剪贴板”
• “把那个命令放到我的剪贴板里”
• “将它作为 HTML 复制”（写入 text/html，这样富文本应用粘贴时会保留格式）

Agent 会调用 clipboard_copy，并将纯净文本直接写入系统剪贴板。没有终端渲染产生的杂乱字符，只有干净的文本。这对 Claude Code 尤其有用（见上文）。

提示：自动复制行为。 默认情况下，只有在你提出要求时，Agent 才会将内容复制到剪贴板。如果希望自动复制命令和代码块，可将以下内容添加到系统提示词中（例如，添加到 Claude Desktop 项目或 Claude Code 的 CLAUDE.md 中）：

当你输出用户可能会粘贴到其他位置的命令或代码块时，请主动使用 clipboard_copy 将其复制到剪贴板。

表格输出格式

剪贴板中包含表格数据时，output_format 用于控制输出格式：

格式	目标位置	输出内容
markdown	Claude、GitHub、大多数工具	GFM 管道表格（默认）
notion	Notion	GFM 管道表格（Notion 可原生渲染此格式）
slack	Slack	*bold* 标题 + 空格对齐的数据，置于等宽代码块中
jira	Jira	||Header|| / |Cell| wiki 标记
confluence	Confluence	与 jira 相同（共用 wiki 语法）
html	邮件、网页、富文本编辑器	带有 <thead>/<th>/<tbody>/<td> 的 <table>
json	API、代码	以标题行为键的对象数组
csv	Excel、数据工具	逗号分隔值

示例：

• “以 Slack 格式读取我的剪贴板” → output_format=slack
• “将我的剪贴板转换为 Jira 表格” → output_format=jira
• “把它作为 HTML 给我” → output_format=html

表格架构推断

添加 include_schema=true，即可同时获取表格和列类型摘要：

“读取我的剪贴板并包含架构”

推断类型：整数、浮点数、货币、百分比、日期、布尔值、文本。每列采用多数判定法——如果没有任何类型占非空单元格的一半以上，该列就会被判定为 text。空单元格会被跳过；表头行不参与推断。

当你将表格数据交给 Claude 生成 SQL CREATE TABLE 语句、Pandas dtype 映射或验证规则时，这项功能很有用——Claude 会预先获得类型信息，而不是从数据中猜测。

提高触发可靠性的提示

服务包含 MCP 指令，用于告知客户端何时使用剪贴板工具，但不同模型和客户端的效果有所差异。如果 Agent 没有领会你的意图，最好明确说明：“把那个复制到我的剪贴板”或“读取我复制的内容”。

如果你可以访问自定义系统提示词（例如 Claude Desktop 项目或自定义 Agent 中的提示词），可以强化此行为：

当用户要求复制输出时，使用 clipboard_copy 将其写入系统剪贴板。当用户引用对话中没有的数据时，使用 clipboard_paste 检查剪贴板。

内容处理

内容类型	处理方式
电子表格	从 HTML/TSV 解析，并按你选择的格式返回（Markdown、JSON、CSV、Slack、Jira、HTML、Notion）
JSON	在 JSON 代码块中美化输出
代码	在围栏代码块中返回
URL	以纯 URL 形式返回
富 HTML（无表格）	移除 HTML 标签，返回易读文本
RTF	在围栏代码块中返回（macOS、Windows 和通过直通方式支持的 Wayland/X11）
纯文本	原样返回
图片（PNG 等）	作为模型可查看和分析的 MCP 图片内容块返回
SVG	可通过 clipboard_read_raw 和 image/svg+xml 作为文本读取，也可通过 clipboard_paste 作为图片返回。可通过 clipboard_copy(mime_type="image/svg+xml") 写入——使用 SVG 的应用（Inkscape、Figma、浏览器）会获取图片。在 Wayland 上，wl-copy 也会自动声明 text/plain，因此编辑器可以直接获取源文本。在 X11 / macOS / Windows 上，SVG 单格式路径仅支持单一 MIME 类型——在多格式同时写入功能合入（#109）之前，不支持 SVG 的应用不会看到任何文本回退内容。
音频 / 视频	不支持；会返回一条说明格式的消息

工作原理

1. 平台检测： 启动时，服务会检测你的剪贴板后端（Wayland、X11、macOS 或 Windows），并选择相应的系统命令。
2. 读取（clipboard_paste）： 调用平台的剪贴板读取命令。优先尝试 text/html（Google Sheets 和 Excel 会将 <table> 标记放到剪贴板上），并使用 Python 内置的 html.parser 解析。若不成功，则依次尝试 text/plain 制表符分隔值、text/rtf，最后检查是否有图片。
3. 写入文本（clipboard_copy）： 将文本传递给平台的剪贴板写入命令（wl-copy、xclip -selection clipboard、pbcopy 或 PowerShell Set-Clipboard）。支持 mime_type 参数，用于写入指定类型的内容（例如 text/html、text/rtf、image/svg+xml）。
4. 写入图片（clipboard_copy_image）： 解码 base64 PNG 或 JPEG 字节，并通过 wl-copy --type、xclip -target、NSPasteboard setData:forType:（macOS）或 Clipboard::SetImage（Windows）写入平台剪贴板。在运行任何子进程之前，会根据声明的 MIME 类型验证魔数。
5. 读取时传递图片： 如果剪贴板中包含图片（PNG 等），则会将其作为 base64 编码的 MCP 图片内容块返回，供模型查看和分析。
6. 内容分类： 将非表格文本内容分类为 JSON、URL、代码或纯文本，并以相应格式返回（美化输出的 JSON、围栏代码块等）。

限制

• 不支持音频和视频。 如果剪贴板中包含音频或视频，服务会报告其格式，但无法返回内容。
• clipboard_copy_image 仅支持写入 PNG 和 JPEG。 直接传递，不重新编码。其他二进制格式（GIF、WebP、TIFF、BMP）目前尚不支持写入。由于 SVG 是 XML，因此通过 clipboard_copy(mime_type="image/svg+xml") 使用类型化文本路径传递。
• Wayland/X11 不支持原子写入多种 MIME 类型。 wl-copy 和 xclip 每次调用只能携带一种 MIME 类型，因此在这些平台上，clipboard_copy_markdown 只会写入 text/html。在 Wayland 上，wl-copy 会为 UTF-8 内容自动声明 text/plain，但返回的字节是渲染后的 HTML 标记（而非 Markdown 源文）——工具运行后，vim 用户粘贴时会看到 <h1>... 等内容。在 X11 上，纯文本目标会得到空剪贴板。若要以纯文本形式粘贴 Markdown 源文，请直接调用 clipboard_copy(markdown_source)。macOS 和 Windows 支持通过 NSPasteboard / DataObject 原子写入多种格式。
• 文本内容会截断至 50KB，以免占用过多模型的上下文窗口。
• 各平台的支持程度不一。 Linux 上的 Wayland 已经过测试并在积极使用中。截至 v2.5.x，Windows 已在 QEMU Windows 客户机上完成端到端测试（期间发现并修复了仅影响 Windows 的 UTF-8 标准输入编码错误，#129）。X11 和 macOS 实现已完成并通过单元测试，但尚未经过进一步验证。欢迎提交错误报告和 PR，尤其是针对 X11 和 macOS 的反馈。

开发

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run the server directly (stdio mode)
uv run mcp-clipboard

# Run with debug logging
uv run mcp-clipboard --debug

# Test with MCP Inspector
uv run mcp dev src/mcp_clipboard/server.py

也可以通过 MCP_CLIPBOARD_DEBUG=1 启用调试日志记录。这在由 Claude Desktop 或 Claude Code 启动服务时很有用。

项目结构

mcp-clipboard/
├── src/mcp_clipboard/
│   ├── __init__.py          # Package version
│   ├── server.py            # MCP server, tool definitions, debug logging
│   ├── clipboard.py         # Platform-agnostic clipboard backend
│   ├── parser.py            # HTML table parser, formatters, content detection
│   ├── instructions/        # Tool and server descriptions (loaded at startup)
│   │   ├── server.md
│   │   ├── clipboard_copy.md
│   │   ├── clipboard_copy_image.md
│   │   ├── clipboard_copy_markdown.md
│   │   ├── clipboard_paste.md
│   │   ├── clipboard_read_raw.md
│   │   ├── clipboard_list_formats.md
│   │   └── clipboard_version.md
│   └── icons/               # SVG icons for MCP client display (light/dark)
│       ├── mcp-clipboard-logo-light.svg
│       └── mcp-clipboard-logo-dark.svg
├── tests/
│   ├── test_parser.py       # Parser and formatter tests
│   └── test_server.py       # Server, backend, and Wayland detection tests
├── .github/
│   ├── workflows/
│   │   ├── publish.yml      # PyPI publish on v* tags (OIDC trusted publisher)
│   │   └── test-publish.yml # TestPyPI publish on test-v* tags
│   └── ISSUE_TEMPLATE/      # Bug report, feature request, platform test forms
├── pyproject.toml
├── CHANGELOG.md
├── CLAUDE.md                # Claude Code project guidance
├── glama.json               # Glama MCP registry metadata
├── LICENSE                  # Apache 2.0
└── README.md

致谢

本项目由人类与 Claude Code（Anthropic 为 Claude 提供的 CLI）协作设计和构建。架构、设计决策和发布管理由人类主导；实现、测试、代码审查和文档编写则通过对话交由 Claude 完成。Claude 编写代码、发现过时文档，并在每次提交中补齐测试覆盖缺口。

许可证

Apache 2.0。详见 LICENSE。

© 2026 Chris Means