
clipboard-mcp-server
io.github.cyanheads/clipboard-mcp-server
Read, write, and inspect the system clipboard on macOS, Linux (X11/Wayland), and Windows via MCP.
Documentation
@cyanheads/clipboard-mcp-server
Read, write, and inspect the system clipboard across macOS, Linux (X11/Wayland), and Windows via MCP. STDIO or Streamable HTTP.
Overview
The system clipboard across macOS, Linux (X11/Wayland), and Windows. Read, write, and inspect text, HTML, RTF, image, and copied-file path content.
Tools
| Tool | Description |
|---|---|
clipboard_read | Read clipboard contents in a specified format (text, HTML, RTF, image, copied-file paths, 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 |
Capability reference
clipboard_read tool
- Read
text,html,rtf,image, orfiles;autoselects the richest present format (files > image > html > rtf > text). Whole-read limits: 512 KB text/HTML/RTF/files, 5 MB image filesreturns the absolute paths of files copied in a file manager, one per line (LF, no trailing newline). They are paths on the machine the server runs on, and the server never opens them. A path holding a line break (on Linux, also one whose bytes are not UTF-8) is left out, and thenoticecounts it- A macOS clipboard can hold several items;
itemCountreports how many, anditem(0-based) reads one alone. Withoutitem, text joins every item's text, RTF is one document built from every item holding text, HTML, or RTF, HTML comes from the first item that has it, an image from the first item holding a PNG (else the first holding another image type), and files list every item; thenoticesays which. Linux and Windows hold one item - Returns
format,content, byte sizes,complete,representationId, anditemCount; images are base64 PNG with optionalwidth/height. Failures carryformat_unavailable(also for anitempast the last),content_too_large,representation_changed,clipboard_unavailable, orinspect_unreadable - For larger values, use byte
offset/limit(minimum limit 4, capped per format), then pass eachnextOffsetasoffsetalong withrepresentationIdand the sameitemuntil complete. Image slices are byte chunks: decode each separately and concatenate in order; only a whole image attaches an image block
clipboard_write tool
- Supply non-empty
contentorclear: true, exclusively;formatacceptstextorhtml, with a 1 MB write limit. HTML gets a tag-stripped plain-text fallback on macOS/Windows that keeps line breaks and tab-separates table cells; Linux plain-text pastes can receive markup - Returns
format/byteSize, orcleared: truewith zero bytes; optionalpreviousContentholds prior plain text within the 512 KB read limit. Failures carrycontent_too_largeorclipboard_unavailable; X11 clear requiresxsel CLIPBOARD_READ_ONLYdisables both writes and clears by removing the tool fromtools/list
clipboard_inspect tool
- Returns
primaryFormat(files > image > html > rtf > text, orempty),availableFormatsfor choosing a read format, anditemCount rawTypeslists platform identifiers with measuredbytes, ormeasurementFailedwhen unreadable. Failures carryinspect_unreadableorclipboard_unavailable
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Clipboard-specific:
- Cross-platform backend detection at startup — macOS (osascript/JXA), 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,filesacross all backends - Copied-file paths —
filesreads each item'spublic.file-urlon macOS,text/uri-listfile:URIs on Linux, and the FileDrop list on Windows, as paths only; no file is opened - Platform-aware HTML writes — macOS and Windows publish HTML plus a tag-stripped plain-text fallback that follows the HTML Standard's
innerTextline-break rules; on Linux the HTML is the only payload, which plain-text paste targets can also receive - Image support — every backend returns PNG as base64, with width/height when the returned bytes carry a readable PNG header (Linux backends read them from that header, so only a whole image or a slice starting at offset 0 has them)
Agent-friendly output:
- Size-guarded I/O — reads and writes over the format limit fail with a typed
content_too_largeerror carrying byte/limit metadata, rather than truncating silently - Bounded continuation —
clipboard_readslices oversized content withoffset/limitandnextOffsetinstead of forcing a single all-or-nothing read, andrepresentationIdmakes a clipboard change between slices fail loudly instead of splicing two values together - Undo support —
clipboard_writereturnspreviousContentso an unintended overwrite can be reverted - Discriminated failure —
format_unavailable,content_too_large,representation_changed,inspect_unreadable, andclipboard_unavailableare typed reasons with recovery hints, not generic errors; each backend classifies its helper's outcomes itself (across wl-clipboard and xclip release spellings), so an empty clipboard, an absent format, and an unreachable helper never blur together
Getting started
Add it to Claude Code:
claude mcp add clipboard-mcp-server -- npx -y @cyanheads/clipboard-mcp-server
For other clients, add this to the MCP config file:
{
"mcpServers": {
"clipboard-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/clipboard-mcp-server"]
}
}
}
Linux needs a clipboard helper installed first — see Prerequisites. For a source build or Streamable HTTP, see Running the server.
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 |
LOG_TOOL_FAILURE_PAYLOADS | Log failed tool arguments/results, capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (16384). Redaction is by key name; secrets inside clipboard content are not redacted. | false |
OTEL_ENABLED | Enable OpenTelemetry instrumentation. | false |
CLIPBOARD_READ_ONLY | Serve the clipboard read-only. When true, clipboard_write is absent from tools/list and uncallable, but listed as disabled in the server manifest, landing page, and startup log. Accepts true/false/1/0/yes/no/on/off; an unrecognized value fails startup. | false |
See .env.example for the full list of optional overrides.
Running the server
Prerequisites
Requires Bun v1.4.4 or higher (or Node.js v24+), plus the platform's clipboard helper:
macOS: No additional tools required — osascript is 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.
apt install xclip xsel # Debian/Ubuntu
pacman -S xclip xsel # Arch
Linux Wayland: wl-clipboard must be installed.
apt install wl-clipboard # Debian/Ubuntu
pacman -S wl-clipboard # Arch
Windows: PowerShell 5.1+ (built-in on Windows 10 and later).
Local development
-
Clone and install:
git clone https://github.com/cyanheads/clipboard-mcp-server.git cd clipboard-mcp-server && bun install -
Build and run:
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:http # listens at http://127.0.0.1:3010/mcp -
Run checks and tests:
bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
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 |
framework-skills/ | Agent workflow skills (add-tool, field-test, polish-docs-meta, etc.) |
Development guide
See CLAUDE.md for the full developer protocol — tool patterns, service patterns, error handling, logging conventions, and the checklist for shipping changes. The short version:
- Handlers throw, framework catches — tool logic catches only to act on a backend's typed outcome: map it to a declared error reason, or move
autoon to the next format - Use
ctx.logfor request-scoped logging - No Docker — this server needs direct host OS access (JXA/NSPasteboard, xclip, wl-clipboard, PowerShell), none of which work inside a container
Contributing
Issues welcome at github.com/cyanheads/clipboard-mcp-server. Run checks and tests before submitting:
bun run devcheck
bun run test
License
Apache 2.0 — see LICENSE.
@cyanheads/clipboard-mcp-servernpm install @cyanheads/clipboard-mcp-server@cyanheads/clipboard-mcp-servernpm install @cyanheads/clipboard-mcp-serverRelated Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.