# clipboard-mcp-server [Health: Active] **Category:** 💻 Developer Tools **Repository:** https://github.com/cyanheads/clipboard-mcp-server **GitHub Stars:** 2 **Views:** 0 **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. ## 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 & README

@cyanheads/clipboard-mcp-server

Read, write, and inspect the system clipboard across macOS, Linux (X11/Wayland), and Windows via MCP. STDIO or Streamable HTTP.

3 Tools

[![Version](https://img.shields.io/badge/Version-0.2.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/clipboard-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/clipboard-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/clipboard-mcp-server/releases/latest/download/clipboard-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=clipboard-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvY2xpcGJvYXJkLW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22clipboard-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fclipboard-mcp-server%22%5D%7D) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
--- ## Tools 3 tools for reading, writing, and inspecting the system clipboard: | Tool | Description | |:---|:---| | `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 | ### `clipboard_read` Read the current clipboard contents in a requested format. - `auto` mode returns the richest format explicitly present — priority: image > html > rtf > text - `image` returns base64-encoded PNG data, with pixel dimensions on every platform whenever the capture carries a readable PNG header - `html` returns raw HTML source as copied from a browser - `rtf` returns raw RTF markup - `text` returns plain text - Size limits: 512 KB for text/HTML/RTF, 5 MB for images (raw bytes before base64 expansion) - Content above the size limit is retrieved in slices with `offset`/`limit` instead of erroring outright: pass both to read a bounded window (`limit` is at least 4 and clamped to the format's size limit) and follow the returned `nextOffset` until `complete` is `true`. Every response carries `totalByteSize` and `complete`; text/HTML/RTF slices never split a multi-byte UTF-8 sequence. Omitting both reads the whole payload as before, still bounded by the size limit - Returns a typed `format_unavailable` error when the requested format is not on the clipboard — use `clipboard_inspect` first to check availability - Returns a typed `content_too_large` error only when no `offset`/`limit` was given and the content exceeds the size limit; the recovery hint points at the slicing parameters above --- ### `clipboard_write` Write content to the clipboard, replacing current contents — or clear it. - `text` writes plain text - `html` writes HTML; macOS and Windows also publish an auto-generated, tag-stripped plain-text fallback, while Linux X11 and Wayland publish only `text/html` - `clear: true` removes every representation instead of writing, so a following `clipboard_inspect` reports `primaryFormat: "empty"`. It returns `cleared: true`, `byteSize: 0`, and no `format`. On Linux X11 this needs `xsel` alongside `xclip` — see [Prerequisites](#prerequisites) - Supply exactly one of `content` or `clear: true`. Omitting both, sending an empty `content`, or combining the two is rejected as invalid arguments rather than silently writing a zero-byte representation - Returns `previousContent` — the plain text that was on the clipboard immediately before the write or clear, so an unintended overwrite can be undone by writing it back. Absent when the clipboard was empty, held no text representation, or its text exceeded the 512 KB read limit - Size limit: 1 MB - `destructiveHint: true` — replaces or removes whatever is currently on the clipboard - Not registered when `CLIPBOARD_READ_ONLY` is set, which gates clearing along with writing — see [Configuration](#configuration) --- ### `clipboard_inspect` List the formats and byte sizes of what is currently on the clipboard without reading the full content. - Returns `primaryFormat` — the richest format present (image > html > rtf > text), or `empty` - Returns `availableFormats` — all semantic formats present, for deciding which format to pass to `clipboard_read` - Returns `rawTypes` — all raw platform type identifiers with byte sizes (UTIs on macOS, TARGETS on X11/Wayland, format names on Windows). An entry whose size could not be measured carries `measurementFailed: true` and no `bytes`, so a failed measurement is never reported as a zero-byte representation - Returns a typed `inspect_unreadable` error when the platform helper's output cannot be read, instead of reporting an empty clipboard - Use this before `clipboard_read` to avoid `format_unavailable` errors and to check content size before reading --- ## Features Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): - Declarative tool definitions — single file per tool, framework handles registration and validation - Unified error handling across all tools - Pluggable auth (`none`, `jwt`, `oauth`) - Structured logging with optional OpenTelemetry tracing - Runs locally via stdio or HTTP from the same codebase Clipboard-specific: - Cross-platform backend detection at startup — macOS (pbcopy/pbpaste + osascript), Linux X11 (xclip), Linux Wayland (wl-clipboard), Windows (PowerShell 5.1+) - Semantic format mapping — platform-native type identifiers (UTIs, TARGETS, Windows format names) mapped to `text`, `html`, `rtf`, `image` across all backends - Size-guarded reads and writes — typed `ContentTooLargeError` with byte/limit metadata before content returns - Platform-aware HTML writes — macOS and Windows publish HTML plus a stripped plain-text fallback; Linux X11 and Wayland publish `text/html` - Image support — macOS and Windows backends decode PNG bytes and return width/height alongside base64 content --- ## Getting started Add the following to your MCP client configuration file. ```json { "mcpServers": { "clipboard-mcp-server": { "type": "stdio", "command": "bunx", "args": ["@cyanheads/clipboard-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` Or with npx (no Bun required): ```json { "mcpServers": { "clipboard-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/clipboard-mcp-server@latest"], "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" } } } } ``` For Streamable HTTP, set the transport and start the server: ```sh MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http # Server listens at http://localhost:3010/mcp ``` ### Prerequisites **macOS:** No additional tools required — `pbcopy`, `pbpaste`, and `osascript` are built in. **Linux X11:** `xclip` must be installed. `xsel` is additionally required for `clipboard_write`'s `clear` mode — it is the only one of the two that can hand the selection back rather than owning an empty one. ```sh apt install xclip xsel # Debian/Ubuntu pacman -S xclip xsel # Arch ``` **Linux Wayland:** `wl-clipboard` must be installed. ```sh apt install wl-clipboard # Debian/Ubuntu pacman -S wl-clipboard # Arch ``` **Windows:** PowerShell 5.1+ (built-in on Windows 10 and later). --- ## Configuration | Variable | Description | Default | |:---------|:------------|:--------| | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` | | `MCP_HTTP_PORT` | Port for HTTP server. | `3010` | | `MCP_HTTP_HOST` | Hostname for HTTP server. | `127.0.0.1` | | `MCP_HTTP_ENDPOINT_PATH` | Endpoint path for the HTTP server. | `/mcp` | | `MCP_HTTP_MAX_BODY_BYTES` | Max inbound JSON-RPC request body, in bytes. Raised above the framework's 1 MiB default so a full-size `clipboard_write` survives JSON escaping (worst case costs 6 wire bytes per source byte). `0` disables the guard and defers to the reverse proxy. | `7340032` | | `MCP_SESSION_MODE` | HTTP session mode: `auto`, `stateful`, or `stateless`. `auto` resolves to `stateful`. This server defaults to `stateless` — it keeps no per-session state. | `stateless` | | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` | | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `notice`, `warning`, `error`). | `info` | | `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` | | `CLIPBOARD_READ_ONLY` | Serve the clipboard read-only. When `true`, `clipboard_write` is not registered — absent from `tools/list` and uncallable, though still shown in a disabled state on the manifest and landing page. Accepts `true/false/1/0/yes/no/on/off`; an unrecognized value fails startup. | `false` | See [`.env.example`](https://github.com/cyanheads/clipboard-mcp-server/blob/HEAD/.env.example) for the full list of optional overrides. --- ## Running the server ### Local development ```sh # One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:http ``` ### Checks and tests ```sh bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite ``` --- ## Project structure | Path | Purpose | |:-----|:--------| | `src/index.ts` | Entry point — registers tools via `createApp()` | | `src/mcp-server/tools/definitions/` | Tool definitions: `clipboard_read`, `clipboard_write`, `clipboard_inspect` | | `src/services/clipboard/` | Platform backends (macOS, Linux X11, Wayland, Windows) and service facade | | `tests/` | Vitest tests for tools and backends | | `skills/` | Agent workflow skills (add-tool, field-test, polish-docs-meta, etc.) | --- ## Development guide See [`CLAUDE.md`](https://github.com/cyanheads/clipboard-mcp-server/blob/HEAD/CLAUDE.md) for the full developer protocol — tool patterns, service patterns, error handling, logging conventions, and the checklist for shipping changes. --- ## Contributing Issues and pull requests welcome at [github.com/cyanheads/clipboard-mcp-server](https://github.com/cyanheads/clipboard-mcp-server). --- ## License Apache 2.0 — see [`LICENSE`](https://github.com/cyanheads/clipboard-mcp-server/blob/HEAD/LICENSE).