
Clipboard
io.github.cmeans由 GitHub 账号 cmeans 发布v2.6.3更新于 Oct 24, 2026
Read and write the system clipboard — tables, text, code, JSON, URLs, images, and more.
概览
本地 MCP 服务器,让助手读写系统剪贴板,保留表格结构,并能返回模型可查看的图片。
- 可以做什么
- 读取剪贴板中的文本、代码、JSON、网址或图片,表格可转换为 Markdown、JSON、CSV、Slack、Jira、HTML 或 Notion 格式,并可推断列类型
- 向剪贴板写入纯文本或指定类型的内容,如 HTML、RTF、SVG
- 把 Markdown 渲染为 HTML,并将两种格式同时放入剪贴板供富文本应用使用
- 从 base64 字节向剪贴板写入 PNG 或 JPEG 图片
- 查看剪贴板当前的 MIME 类型,并按指定类型读取原始内容
- 在 Linux 上读取 X11/Wayland 的 PRIMARY 选区而非 Ctrl-C 剪贴板
- 适用场景
- 当你复制了表格单元格、代码、JSON 或图片,希望助手在不丢失结构的情况下读取,或希望把生成的命令和代码块干净地放入剪贴板、而不是从终端复制带换行和缩进的文本时适用。
- 运行要求
- 作为本地 stdio 进程由 MCP 客户端启动。需要 pipx 或 uv 等 Python 包运行器来安装并运行 PyPI 包。Linux 还需 wl-clipboard(Wayland)或 xclip(X11);macOS 与 Windows 使用系统自带工具。可选环境变量 MCP_CLIPBOARD_DEBUG、WAYLAND_DISPLAY、XDG_RUNTIME_DIR、XDG_SESSION_TYPE 用于调整检测与日志。
安装
在 SourceWeft 中
- 打开 控制台中的 Clipboard,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
mcp-clipboard
[PyPI version] [Python versions] [License] [CI] [Coverage] [Downloads] [Glama]
[pip downloads] [pipenv downloads] [pipx downloads] [uv downloads] [poetry downloads] [pdm downloads]
[linux downloads] [macos downloads] [windows downloads]
An MCP server that gives your AI assistant direct access to your system clipboard: read what you copied, or write clean text straight to it. Works with any MCP-compatible client, including Claude Code, Claude Desktop, Cursor, Windsurf, and others.
Why This Exists
Pasting loses structure
When you copy cells from Google Sheets or Excel and paste into a chat input, the tabular structure (rows and columns) is destroyed. It arrives as a flat string with no delimiters. The model has to guess where one cell ends and the next begins, and it often guesses wrong.
mcp-clipboard preserves it. Instead of pasting, tell your assistant to "read my clipboard." The server reads the clipboard directly, detects tabular data from the HTML that spreadsheet apps put on the clipboard, and returns it as a properly formatted Markdown table, JSON, or CSV. No structure lost, no guessing.
Bonus: it also fixes copying from Claude Code
Claude Code's terminal renderer adds 2-character padding, hard line breaks at ~80 columns, and trailing whitespace to all output. When you select and copy text from the terminal, those artifacts come along for the ride:
This has been reported repeatedly on the claude-code repo (issues #4686, #6827, #7670, #13378, #15199, #25040, #25427, #26016) with dozens of upvotes and no fix shipped.
mcp-clipboard sidesteps the problem entirely. Instead of copying text from the terminal, ask Claude Code to put it on your clipboard:
"Copy that command to my clipboard"
Claude Code calls clipboard_copy, writes the clean text directly to your system clipboard, and you paste it wherever you need it. No padding, no hard wraps, no cleanup.
Tip: To make this automatic, add a line to your project or global CLAUDE.md:
Claude Code will then copy every command it suggests without you having to ask.
Bonus: read your X11/Wayland selection without Ctrl-C
Linux desktops have two clipboards: the CLIPBOARD that Ctrl-C / Ctrl-V uses, and the PRIMARY selection. PRIMARY is whatever text you currently have highlighted, pasted by middle-click. It updates as soon as you select something; you don't have to copy it.
mcp-clipboard reads PRIMARY too. Pass selection="primary" to clipboard_paste, clipboard_read_raw, or clipboard_list_formats and the server reads the selection buffer instead of the Ctrl-C clipboard. Some workflows this enables:
- Terminal triage. An error message scrolls past, mouse-select it, ask the model what it means. Your Ctrl-C buffer stays intact for whatever you had on it.
- vim / IDE visual selection.
v-select a function, ask the model to explain it or refactor it. - Browser / PDF reading. Drag-select a paragraph, ask "what's this saying?" without leaving the reading flow.
- Two-buffer workflows. Keep a snippet in CLIPBOARD (Ctrl-C) and pull a different one through PRIMARY in the same conversation.
Linux only. macOS and Windows have no equivalent buffer; passing selection="primary" on those platforms returns a clear error.
Tools
Setup
Step 1: Install a Python package runner
mcp-clipboard is a Python package on PyPI. Any Python tool that can install and launch console-script entry points works for running it as an MCP server. The two most common choices are pipx and uv; both appear in the install-counts badges at the top of this README and both are in active use. Pick whichever you have or prefer:
- pipx: install instructions per platform are in the official pipx install docs. On most distros pipx is available via the system package manager (
apt,dnf,pacman,brew, etc.). - uv: install instructions per platform are in the official uv install docs. Astral documents package-manager paths, signed standalone-binary downloads, and shell installers for each platform.
Verify your chosen runner is on PATH:
The rest of this section shows commands for both runners; substitute the one you installed.
Step 2: Install the platform clipboard tool (Linux only)
macOS and Windows have everything they need built in. Linux needs one CLI utility:
Platform status: Linux with Wayland is tested and actively used. Windows has been exercised end-to-end on a QEMU Windows guest (a real Windows-only encoding bug, #129, was found and fixed via that testing in v2.5.x). X11 and macOS implementations are complete but unverified beyond the unit tests. Bug reports and PRs are welcome.
Step 3: Verify mcp-clipboard works on your system
Before wiring it into a client, confirm the package installs and detects your platform correctly. With pipx:
Or with uv:
Both forms fetch the package on demand without a permanent install (use pipx install mcp-clipboard or uv tool install mcp-clipboard first if you'd rather install it persistently). Expected output:
If you see Backend: NOT AVAILABLE, follow the platform-specific hint in the error message (typically: install the Linux clipboard tool from Step 2) and re-run.
Step 4: Register the server with your MCP client
The MCP host launches mcp-clipboard via a command + args pair. Both pipx and uv expose a one-shot run subcommand that fetches and executes the package, so the most convenient configs use those forms.
Claude Code
With pipx:
With uv:
Claude Desktop
Locate your Claude Desktop config file (paste the path into your file manager's address bar to jump straight there):
- Linux:
~/.config/Claude/claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add an entry to mcpServers using one of the forms below. With pipx:
Or with uv:
Save the file, then fully quit and relaunch Claude Desktop for the new server to load.
Windows tip: Claude Desktop caches the environment (including
PATH) from the moment it launches. Ifpipx/uvxwas installed after Claude Desktop was started, Claude Desktop will not see it until restart. If the snippet above produces "Server failed to start" or a "command not found" style error in the MCP logs, right-click the Claude Desktop tray icon, choose Quit, then reopen Claude Desktop. A taskbar-X close just hides the window; the cached environment is still there.
Other MCP clients
Any client that supports MCP stdio servers can use mcp-clipboard. Common one-shot forms are pipx run mcp-clipboard and uvx mcp-clipboard; if you've installed mcp-clipboard persistently (pipx install mcp-clipboard or uv tool install mcp-clipboard), the resulting mcp-clipboard binary on PATH also works as the command. Consult your client's documentation for how to register MCP servers.
Step 5: Confirm it works end-to-end
In your client, ask:
What's on my clipboard?
The client should call clipboard_paste and return the content. If you copied a spreadsheet selection or a URL beforehand, you'll see it formatted appropriately.
If nothing happens or you get a tool error, re-run --check (whichever runner you used in Step 3) to confirm the package install is healthy, then check your client's MCP server logs (each MCP host exposes them differently; consult your client's documentation).
Upgrading
A persistent install never updates itself, and uvx mcp-clipboard runs the uv tool installed copy when one exists instead of fetching a newer release. Upgrade it explicitly:
The one-shot runners can also reuse a cached copy. uvx mcp-clipboard@latest and pipx run --no-cache mcp-clipboard force a fresh check. Run --version to confirm which version you have, then restart your MCP client so it launches the new one.
Installing from source
If you prefer a local clone instead of installing from PyPI:
Then point your client at the local install:
Environment variables
Environment variables can be passed via the "env" key in the config.
Most Linux users won't need to set any of these. Override if auto-detection fails (multiple compositors, non-standard socket path, or containerized environments).
Usage
Reading your clipboard
Copy anything (spreadsheet cells, code, text, a URL, JSON, an image), then:
- "Paste my clipboard"
- "Read my clipboard"
- "What's on my clipboard?"
- "I copied some data, take a look"
Your assistant calls clipboard_paste and returns the content with structure preserved.
Writing to your clipboard
When your agent generates a command, code block, or any text you need to use elsewhere:
- "Copy that to my clipboard"
- "Put that command on my clipboard"
- "Copy that as HTML" (writes
text/htmlso rich-text apps paste with formatting)
The agent calls clipboard_copy and the clean text goes straight to your system clipboard. No terminal rendering artifacts, just clean text. This is especially useful with Claude Code (see above).
Tip: auto-copy behavior. By default the agent only copies to the clipboard when you ask. If you want commands and code blocks copied automatically, add this to your system prompt (e.g. in a Claude Desktop project or Claude Code's CLAUDE.md):
When you output a command or code block that the user is likely to paste elsewhere, proactively copy it to the clipboard using clipboard_copy.
Table output formats
When the clipboard contains tabular data, output_format controls the format:
Examples:
- "Read my clipboard as Slack" →
output_format=slack - "Convert my clipboard to Jira table" →
output_format=jira - "Give me that as HTML" →
output_format=html
Table schema inference
Add include_schema=true to get a column-type summary alongside the table:
"Read my clipboard with schema"
Inferred types: integer, float, currency, percentage, date, boolean, text. Uses majority-wins per column — if no type accounts for more than half the non-empty cells, the column is typed as text. Empty cells are skipped; the header row is excluded from inference.
This is useful when handing tabular data to Claude for SQL CREATE TABLE statements, Pandas dtype mappings, or validation rules — Claude gets the types upfront instead of guessing from the data.
Tips for reliable triggering
The server includes MCP instructions that tell the client when to use the clipboard tools, but results vary by model and client. If the agent doesn't pick up on your intent, be explicit: "copy that to my clipboard" or "read what I copied" work most reliably.
If you have access to a custom system prompt (e.g. in a Claude Desktop project or a custom agent), you can reinforce the behavior:
When the user asks to copy output, use clipboard_copy to write it to the system clipboard. When the user references data not in the conversation, check the clipboard using clipboard_paste.
Content handling
How It Works
- Platform detection: At startup, the server detects your clipboard backend (Wayland, X11, macOS, or Windows) and selects the appropriate system commands.
- Reading (
clipboard_paste): Calls the platform's clipboard read command. Triestext/htmlfirst (Google Sheets and Excel put<table>markup on the clipboard), parses with Python's built-inhtml.parser. Falls back totext/plaintab-separated values, thentext/rtf, then checks for images. - Writing text (
clipboard_copy): Pipes text to the platform's clipboard write command (wl-copy,xclip -selection clipboard,pbcopy, or PowerShellSet-Clipboard). Supports amime_typeparameter for writing typed content (e.g.text/html,text/rtf,image/svg+xml). - Writing images (
clipboard_copy_image): Decodes base64 PNG or JPEG bytes and writes them to the platform's clipboard viawl-copy --type,xclip -target, NSPasteboardsetData:forType:(macOS), orClipboard::SetImage(Windows). Magic bytes are validated against the declared MIME type before any subprocess runs. - Image passthrough on read: If the clipboard contains an image (PNG, etc.), it's returned as a base64-encoded MCP image content block that the model can see and analyze.
- Content classification: Non-tabular text content is classified as JSON, URL, code, or plain text and returned with appropriate formatting (pretty-printed JSON, fenced code blocks, etc.).
Limitations
- Audio and video are not supported. If the clipboard contains audio or video, the server reports the format but cannot return the content.
- Image write supports PNG and JPEG only via
clipboard_copy_image. Pass-through, no re-encoding. Other binary formats (GIF, WebP, TIFF, BMP) are not yet writable. SVG rides the typed-text path viaclipboard_copy(mime_type="image/svg+xml")since SVG is XML. - Writing multiple MIME types atomically is not supported on Wayland/X11.
wl-copyandxclipcarry a single MIME per invocation, soclipboard_copy_markdownwrites onlytext/htmlon those platforms. On Wayland,wl-copyauto-advertisestext/plainfor UTF-8 content but the bytes returned are the rendered HTML markup (not the markdown source) — vim users pasting after the tool runs will see<h1>...etc. On X11, plain-text targets see an empty clipboard. For a plain-text paste of the markdown source, callclipboard_copy(markdown_source)directly. macOS and Windows do support atomic multi-format writes via NSPasteboard /DataObject. - Text content is truncated at 50KB to avoid overwhelming the model's context window.
- Platform coverage is uneven. Linux with Wayland is tested and actively used. Windows has been exercised end-to-end on a QEMU Windows guest as of v2.5.x (which surfaced and resolved a Windows-only UTF-8 stdin encoding bug, #129). X11 and macOS implementations are complete and have unit tests but have not been verified beyond that. Bug reports and PRs are welcome, especially for X11 and macOS.
Development
Debug logging can also be enabled via MCP_CLIPBOARD_DEBUG=1, which is useful when the server is launched by Claude Desktop or Claude Code.
Project structure
Acknowledgments
This project was designed and built in collaboration with Claude Code (Anthropic's CLI for Claude). Architecture, design decisions, and release management were driven by the human; implementation, testing, code review, and documentation were delegated conversationally, with Claude writing code, catching stale docs, and filling test coverage gaps across every commit.
License
Apache 2.0. See LICENSE.
[图片] © 2026 Chris Means来源:README.md,提交 18e7dce
工具
0版本历史
3- v2.6.3最新Oct 19, 2026
- v2.6.2Oct 7, 2026
- v2.6.1Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分