
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, and image content.
Tools
| 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 |
Capability reference
clipboard_read tool
- Read
text,html,rtf, orimage;autoselects the richest present format (image > html > rtf > text). Whole-read limits: 512 KB text/HTML/RTF, 5 MB image - Returns
format,content, byte sizes,complete, andrepresentationId; images are base64 PNG with optionalwidth/height. Failures carryformat_unavailable,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 withrepresentationIduntil 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 stripped plain-text fallback on macOS/Windows; 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(image > html > rtf > text, orempty) andavailableFormatsfor choosing a read format 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,imageacross all backends - Platform-aware HTML writes — macOS and Windows publish HTML plus a stripped plain-text fallback; 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.0 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.