Mcp Clipboard

mcp-clipboard

[](https://pypi.org/project/mcp-clipboard/) [](https://pypi.org/project/mcp-clipboard/) [](https://github.com/cmeans/mcp-clipboard/blob/main/LICENSE) [](https://github.com/cmeans/mcp-clipboard/actions/workflows/ci.yml) [](https://codecov.io/gh/cmeans/mcp-clipboard) [](https://github.com/cmeans/pypi-winnow-downloads)

[](https://pypi.org/project/mcp-clipboard/) [](https://pypi.org/project/mcp-clipboard/) [](https://pypi.org/project/mcp-clipboard/) [](https://pypi.org/project/mcp-clipboard/) [](https://pypi.org/project/mcp-clipboard/) [](https://pypi.org/project/mcp-clipboard/)

[](https://pypi.org/project/mcp-clipboard/) [](https://pypi.org/project/mcp-clipboard/) [](https://pypi.org/project/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

| Tool | Description | | --- | --- | | clipboard_paste | Primary tool. Read any clipboard content: tables, text, code, JSON, URLs, images. Tables are formatted as Markdown/JSON/CSV; pass include_schema=true to append inferred column types. Images are returned as image content the model can see. Optional selection="primary" reads the X11/Wayland PRIMARY selection (middle-click / select-text-to-paste buffer) instead of the default Ctrl-C clipboard. | | clipboard_copy | Write text content to the system clipboard. Accepts an optional mime_type parameter (text/plain by default; also text/html, text/rtf, image/svg+xml, or any text/* on Wayland/X11). | | clipboard_copy_markdown | Render markdown to HTML and place both formats on the clipboard so paste targets pick the right one — Slack/Gmail/Notion/Discord get rich text; vim/terminal get the source. macOS/Windows write both atomically; Wayland/X11 are single-MIME and write only text/html. | | clipboard_copy_image | Write a PNG or JPEG image to the system clipboard from base64-encoded bytes. Pass-through with no re-encoding; magic bytes are validated against the declared MIME. Use clipboard_copy for text. | | clipboard_list_formats | List what MIME types are currently on the clipboard. Accepts selection="primary" for the X11/Wayland PRIMARY selection. | | clipboard_read_raw | Return raw clipboard content for a given MIME type (diagnostic). Any non-binary type passes through; only image/*, audio/*, video/*, and application/octet-stream are rejected. Use clipboard_paste for images. Accepts selection="primary" for the X11/Wayland PRIMARY selection. | | clipboard_version | Return the running mcp-clipboard package version as {"name": "mcp-clipboard", "version": ""}. Diagnostic. Useful for hosts that don't surface the standard MCP serverInfo block to the model, and for test harnesses that need to record which build served a given run. |

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 | Tool | Install | | --- | --- | --- | | 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 or sudo apt install xclip | | macOS | Built-in | No install needed (pbcopy / pbpaste) | | Windows | Built-in | No install needed (PowerShell) |

> 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):

• 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:

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

Or with uv:

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

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. If pipx/uvx was 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).

Installing from source

If you prefer a local clone instead of installing from PyPI:

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

Then point your client at the local install:

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

Environment variables

Environment variables can be passed via the "env" key in the config.

| Variable | Platform | Purpose | Default | | --- | --- | --- | --- | | MCP_CLIPBOARD_DEBUG | All | Enable debug logging (1 to enable) | Off | | WAYLAND_DISPLAY | Linux (Wayland) | Compositor socket name or absolute path | Auto-detected | | XDG_RUNTIME_DIR | Linux (Wayland) | Directory containing the Wayland socket | /run/user/ | | XDG_SESSION_TYPE | Linux | Session type hint (wayland or x11) | Auto-detected via socket scan |

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/html so 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](#bonus-it-also-fixes-copying-from-claude-code)).

> 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:

| Format | Destination | What you get | |--------|-------------|--------------| | markdown | Claude, GitHub, most tools | GFM pipe table (default) | | notion | Notion | GFM pipe table (Notion renders these natively) | | slack | Slack | *bold* header + space-aligned data in a monospace code block | | jira | Jira | \|\|Header\|\| / \|Cell\| wiki markup | | confluence | Confluence | same as jira (shared wiki syntax) | | html | Email, web, rich-text editors | ` with /// | | json | APIs, code | Array of objects keyed by header row | | csv` | Excel, data tools | Comma-separated values |

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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cmeans
• Source: cmeans/mcp-clipboard
• License: Apache-2.0
• Homepage: https://pypi.org/project/mcp-clipboard/

Install and usage instructions live in the source repository linked above.