# clipboard-mcp-server [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/cyanheads/clipboard-mcp-server  
**GitHub Stars:** 2  
**npm Downloads (last month):** 1308  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/clipboard-mcp-server

## Description
Read, write, and inspect the system clipboard on macOS, Linux (X11/Wayland), and Windows via MCP.

## Tools
Capabilities this server exposes over MCP:

- **clipboard_read** — Read clipboard contents in a specified format (text, HTML, RTF, image, or auto-select richest)
- **clipboard_write** — Write plain text or HTML to the clipboard, replacing current contents, or clear it outright
- **clipboard_inspect** — List available clipboard formats and byte sizes without reading full content

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `bunx` (confidence: high):

```json
"mcpServers": {
  "clipboard-mcp-server": {
    "command": "bunx",
    "args": ["@cyanheads/clipboard-mcp-server@latest"]
  }
}
```

## Documentation

## What clipboard-mcp-server MCP server does

clipboard-mcp-server MCP server connects an MCP client to the host operating system's clipboard. It supports macOS, Linux using X11 or Wayland, and Windows. The server maps platform-specific clipboard types to four common formats: text, HTML, RTF, and image.

The `clipboard_read` tool retrieves a requested format or chooses the richest available representation. The `clipboard_write` tool replaces the clipboard with plain text or HTML, or clears all clipboard representations. The `clipboard_inspect` tool reports available formats and platform-native type identifiers without returning the full payload.

This is useful for agents that need to move content between applications, inspect whether rich content is available before reading it, or preserve enough state to undo an accidental overwrite.

## How it works

The server detects a clipboard backend when it starts. macOS uses `osascript`/JXA, Linux uses `xclip` for X11 or `wl-clipboard` for Wayland, and Windows uses PowerShell 5.1 or later. Native identifiers such as macOS UTIs, X11 or Wayland targets, and Windows format names are translated into the common format names exposed through MCP.

Reads are size guarded. Text, HTML, and RTF are limited to 512 KB, while images are limited to 5 MB before base64 expansion. Larger values can be read in bounded slices using `offset` and `limit`. The response includes a `nextOffset` and a `representationId`; if the clipboard changes during continuation, the read fails rather than combining bytes from different values. Complete images are returned as base64-encoded PNG data, with dimensions when a readable PNG header is available.

HTML writes behave differently by platform. macOS and Windows also publish stripped plain text, while Linux may expose the markup to plain-text paste targets. Writes return the previous plain-text clipboard value when it can be read, supporting an application-level undo flow.

## Setup and configuration

The package can run as a stdio process or as a local Streamable HTTP server. MCP clients can launch it through the npm package, and the repository provides installation links for Claude Desktop, Cursor, and VS Code.

Linux users need the backend utility for their display session: `xclip` for X11 or `wl-clipboard` for Wayland. Clearing the clipboard on Linux X11 also requires `xsel` alongside `xclip`. If a helper is missing or cannot reach the desktop session, operations return a typed `clipboard_unavailable` error.

Set `CLIPBOARD_READ_ONLY` to disable writing and clearing. When enabled, `clipboard_write` is not registered.

## Tools and capabilities

- `clipboard_read` accepts `text`, `html`, `rtf`, `image`, or `auto`. Automatic selection prefers image, then HTML, RTF, and text, moving to the next readable format when necessary.
- `clipboard_write` accepts exactly one of content or `clear: true`. It rejects empty content and invalid combinations, and reports `content_too_large` for values over 1 MB.
- `clipboard_inspect` returns the richest detected format, readable available formats, raw platform types, and measured byte sizes. Unmeasurable or unreadable types are distinguished from empty values.
- Typed errors include `format_unavailable`, `content_too_large`, `representation_changed`, `inspect_unreadable`, and `clipboard_unavailable`.
- Empty but present formats return empty content rather than being treated as missing.

The clipboard-mcp-server MCP server is therefore best suited to desktop-hosted agents whose MCP process can access the active user session. It is not a general remote clipboard service; its operations depend on the local platform helper and desktop connection.

## Limitations and notes

Image slices are PNG byte chunks, not independently viewable images. Consumers must decode each base64 chunk and concatenate the bytes in offset order. A requested format that is absent, or a clipboard with no usable representation, produces `format_unavailable`.

The `previousContent` field is omitted when the clipboard was empty, has no text representation, or contains text beyond the 512 KB read limit. Linux HTML behavior can also result in raw HTML being pasted into a plain-text target, especially on X11.

The clipboard-mcp-server MCP server does not silently truncate oversized reads or writes. Applications should handle the typed errors and continuation metadata explicitly when working with large or changing clipboard values.

_Full upstream README: https://allmcps.com/mcp/clipboard-mcp-server/readme_