clipboard-mcp-server

Overview

The system clipboard across macOS, Linux (X11/Wayland), and Windows. Read, write, and inspect text, HTML, RTF, and image content.

Tools

Related MCP server: mcp-clipboard

Capability reference

clipboard_read tool

• Read text, html, rtf, or image; auto selects 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, and representationId; images are base64 PNG with optional width/height. Failures carry format_unavailable, content_too_large, representation_changed, clipboard_unavailable, or inspect_unreadable

• For larger values, use byte offset/limit (minimum limit 4, capped per format), then pass each nextOffset as offset along with representationId until 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 content or clear: true, exclusively; format accepts text or html, 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, or cleared: true with zero bytes; optional previousContent holds prior plain text within the 512 KB read limit. Failures carry content_too_large or clipboard_unavailable; X11 clear requires xsel

• CLIPBOARD_READ_ONLY disables both writes and clears by removing the tool from tools/list

clipboard_inspect tool

• Returns primaryFormat (image > html > rtf > text, or empty) and availableFormats for choosing a read format

• rawTypes lists platform identifiers with measured bytes, or measurementFailed when unreadable. Failures carry inspect_unreadable or clipboard_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 across 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_large error carrying byte/limit metadata, rather than truncating silently

• Bounded continuation — clipboard_read slices oversized content with offset/limit and nextOffset instead of forcing a single all-or-nothing read, and representationId makes a clipboard change between slices fail loudly instead of splicing two values together

• Undo support — clipboard_write returns previousContent so an unintended overwrite can be reverted

• Discriminated failure — format_unavailable, content_too_large, representation_changed, inspect_unreadable, and clipboard_unavailable are 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

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

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 auto on to the next format

• Use ctx.log for 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.