mcp-clipboard

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cmeans/mcp-clipboard/main/src/mcp_clipboard/icons/mcp-clipboard-logo-dark.svg" width="128">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/cmeans/mcp-clipboard/main/src/mcp_clipboard/icons/mcp-clipboard-logo-light.svg" width="128">
    <img src="https://raw.githubusercontent.com/cmeans/mcp-clipboard/main/src/mcp_clipboard/icons/mcp-clipboard-logo-light.svg" alt="mcp-clipboard logo" width="128">
  </picture>
</p>

# mcp-clipboard

[![PyPI version](https://img.shields.io/pypi/v/mcp-clipboard)](https://pypi.org/project/mcp-clipboard/)
[![Python versions](https://img.shields.io/pypi/pyversions/mcp-clipboard)](https://pypi.org/project/mcp-clipboard/)
[![License](https://img.shields.io/pypi/l/mcp-clipboard)](https://github.com/cmeans/mcp-clipboard/blob/main/LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/cmeans/mcp-clipboard/ci.yml?label=CI)](https://github.com/cmeans/mcp-clipboard/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/cmeans/mcp-clipboard/graph/badge.svg)](https://codecov.io/gh/cmeans/mcp-clipboard)
[![Downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Fdownloads-30d-non-ci.json)](https://github.com/cmeans/pypi-winnow-downloads)
[![Glama](https://glama.ai/mcp/servers/cmeans/mcp-clipboard/badges/score.svg)](https://glama.ai/mcp/servers/cmeans/mcp-clipboard)

[![pip downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Finstaller-pip-30d-non-ci.json)](https://pypi.org/project/mcp-clipboard/)
[![pipenv downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Finstaller-pipenv-30d-non-ci.json)](https://pypi.org/project/mcp-clipboard/)
[![pipx downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Finstaller-pipx-30d-non-ci.json)](https://pypi.org/project/mcp-clipboard/)
[![uv downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Finstaller-uv-30d-non-ci.json)](https://pypi.org/project/mcp-clipboard/)
[![poetry downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Finstaller-poetry-30d-non-ci.json)](https://pypi.org/project/mcp-clipboard/)
[![pdm downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Finstaller-pdm-30d-non-ci.json)](https://pypi.org/project/mcp-clipboard/)

[![linux downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Fos-linux-30d-non-ci.json)](https://pypi.org/project/mcp-clipboard/)
[![macos downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Fos-macos-30d-non-ci.json)](https://pypi.org/project/mcp-clipboard/)
[![windows downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fpypi-badges.intfar.com%2Fmcp-clipboard%2Fos-windows-30d-non-ci.json)](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.

<!-- mcp-name: io.github.cmeans/mcp-clipboard -->

## 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": "<x.y.z>"}`. 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](https://pipx.pypa.io/) and [uv](https://docs.astral.sh/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](https://pipx.pypa.io/stable/how-to/install-pipx/). 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](https://docs.astral.sh/uv/getting-started/installation/). Astral documents package-manager paths, signed standalone-binary downloads, and shell installers for each platform.

Verify your chosen runner is on `PATH`:

```bash
pipx --version   # if you chose pipx
```

```bash
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)** |