clipboard-mcp-server

---

概述

适用于 macOS、Linux（X11/Wayland）和 Windows 的系统剪贴板。可通过任何 MCP 客户端读取、写入和检查文本、HTML、RTF 及图像内容。可作为 stdio 进程或本地 Streamable HTTP 服务运行。

工具

工具	描述
clipboard_read	以指定格式读取剪贴板内容（文本、HTML、RTF、图像，或自动选择内容最丰富的格式）
clipboard_write	将纯文本或 HTML 写入剪贴板并替换当前内容，或直接清空剪贴板
clipboard_inspect	列出可用的剪贴板格式及字节大小，而不读取完整内容

---

功能参考

clipboard_read _工具

• 读取 text、html、rtf 或 image；auto 会选择当前内容最丰富的格式（image > html > rtf > text）。整段读取上限：文本/HTML/RTF 为 512 KB，图像为 5 MB
• 返回 format、content、字节大小、complete 和 representationId；图像为 base64 PNG，并可选返回 width/height。失败时会返回 format_unavailable、content_too_large、representation_changed、clipboard_unavailable 或 inspect_unreadable
• 对于较大的内容，可使用字节 offset/limit 分段读取（最小 limit 为 4，并按格式设有上限），然后将每个 nextOffset 与 representationId 一起作为 offset 传入，直至读取完成。图像分段是字节块：分别解码每块并按顺序拼接；只有整幅图像才会附带图像块

---

clipboard_write _工具

• 必须仅提供非空的 content 或 clear: true；format 接受 text 或 html，写入上限为 1 MB。在 macOS/Windows 上，HTML 会生成去除标记后的纯文本备用内容；在 Linux 上，纯文本粘贴可能会收到标记内容
• 返回 format/byteSize，或返回 cleared: true 且字节数为零；可选的 previousContent 保存了 512 KB 读取上限内的先前纯文本。失败时会附带 content_too_large 或 clipboard_unavailable；X11 清空需要 xsel
• 设置 CLIPBOARD_READ_ONLY 后，工具会从 tools/list 中移除，从而禁用写入和清空操作

---

clipboard_inspect _工具

• 返回 primaryFormat（优先级为 image > html > rtf > text，或为 empty）以及 availableFormats，以便选择读取格式
• rawTypes 列出平台标识及测得的 bytes；无法读取时会显示 measurementFailed。失败时会附带 inspect_unreadable 或 clipboard_unavailable

---

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

剪贴板专属功能：

• 启动时检测跨平台后端：macOS（osascript/JXA）、Linux X11（xclip）、Linux Wayland（wl-clipboard）、Windows（PowerShell 5.1+）
• 语义格式映射：将平台原生类型标识符（UTI、TARGETS、Windows 格式名称）映射为所有后端通用的 text、html、rtf、image
• 平台适配的 HTML 写入：macOS 和 Windows 会发布 HTML 及去除标记后的纯文本备用内容；在 Linux 上，HTML 是唯一的载荷，纯文本粘贴目标也可以接收该内容
• 图像支持：所有后端均以 base64 格式返回 PNG，并提供宽度/高度（Linux 后端会从 PNG 标头中读取）

便于 Agent 使用的输出：

• 有大小限制的 I/O：超出格式限制的读取和写入会失败，并返回携带字节数/限制元数据的类型化 content_too_large 错误，而不会静默截断
• 有界续读：clipboard_read 使用 offset/limit 对超大内容分片，并返回 nextOffset，而不强制一次性完整读取；representationId 可确保分片期间剪贴板发生变化时明确报错，而不是将两个值拼接在一起
• 撤销支持：clipboard_write 会返回 previousContent，以便还原意外覆盖的内容
• 可区分的失败原因：format_unavailable、content_too_large、representation_changed、inspect_unreadable 和 clipboard_unavailable 是带有恢复提示的类型化原因，而非通用错误；每个后端都会自行对辅助程序的结果进行分类（包括 wl-clipboard 和 xclip 的不同退出状态写法），因此不会混淆剪贴板为空、格式不存在和辅助程序无法访问这几种情况

---

入门

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "clipboard-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/clipboard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "clipboard-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/clipboard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

Bun 1.4.0+ 或 Node.js 24+。

macOS： 无需额外工具，系统已内置 osascript。

Linux X11： 必须安装 xclip。clipboard_write 的 clear 模式还需要 xsel——在这两种工具中，只有它能交还选区，而不是持有一个空选区。

apt install xclip xsel      # Debian/Ubuntu
pacman -S xclip xsel        # Arch

Linux Wayland： 必须安装 wl-clipboard。

apt install wl-clipboard    # Debian/Ubuntu
pacman -S wl-clipboard      # Arch

Windows： PowerShell 5.1+（Windows 10 及更高版本内置）。

---

配置

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_HOST	HTTP 服务的主机名。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP 服务的端点路径。	/mcp
MCP_HTTP_MAX_BODY_BYTES	入站 JSON-RPC 请求正文的最大字节数。该值高于框架默认的 1 MiB，以确保完整大小的 clipboard_write 在经过 JSON 转义后仍能正常处理（最坏情况下，每个源字节会占用 6 个传输字节）。0 会禁用此限制，并交由反向代理处理。	7340032
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。auto 会解析为 stateful。此服务默认使用 stateless，不会保留任何会话状态。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录失败的工具参数/结果，最多为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（16384）字节。按键名进行脱敏；剪贴板内容中的机密不会脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false
CLIPBOARD_READ_ONLY	以只读方式提供剪贴板服务。设为 true 时，clipboard_write 不会出现在清单和 tools/list 中，也无法调用，但会在落地页和启动日志中显示为已禁用。接受 true/false/1/0/yes/no/on/off；无法识别的值会导致启动失败。	false

完整的可选覆盖项列表请参见 .env.example。

---

运行服务

本地开发

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

检查与测试

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite

---

项目结构

路径	用途
src/index.ts	入口点 — 通过 createApp() 注册工具
src/mcp-server/tools/definitions/	工具定义：clipboard_read、clipboard_write、clipboard_inspect
src/services/clipboard/	平台后端（macOS、Linux X11、Wayland、Windows）和服务门面
tests/	针对工具和后端的 Vitest 测试
framework-skills/	Agent 工作流技能（add-tool、field-test、polish-docs-meta 等）

---

开发指南

完整的开发规范请参见 CLAUDE.md，其中包括工具模式、服务模式、错误处理、日志约定，以及发布变更的检查清单。简而言之：

• 处理器抛出异常，由框架捕获 — 工具逻辑仅在需要处理后端的类型化结果时捕获异常：将其映射到已声明的错误原因，或让 auto 继续尝试下一种格式
• 使用 ctx.log 记录请求范围内的日志
• 不使用 Docker — 此服务需要直接访问主机操作系统（JXA/NSPasteboard、xclip、wl-clipboard、PowerShell），这些都无法在容器内运行

---

贡献

欢迎在 github.com/cyanheads/clipboard-mcp-server 提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache 2.0 — 详见 LICENSE。