Clipboard

mcp-clipboard

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:

  echo "this is a long command that wraps and

breaks when you paste it because of the hard newlines and leading spaces"

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:

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

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:

pipx --version   # if you chose pipx

uv --version     # if you chose uv

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:

pipx run mcp-clipboard --check

Or with uv:

uvx mcp-clipboard --check

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:

mcp-clipboard 2.5.1

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

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:

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

With uv:

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

Claude Desktop

Locate your Claude Desktop config file (paste the path into your file manager's address bar to jump straight there):

• **Li