Repository avatar
Other Tools
v0.3.1
active

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.

3 Tools

Version License MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework


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

ToolDescription
clipboard_readRead clipboard contents in a specified format (text, HTML, RTF, image, copied-file paths, or auto-select richest)
clipboard_writeWrite plain text or HTML to the clipboard, replacing current contents, or clear it outright
clipboard_inspectList available clipboard formats and byte sizes without reading full content

Capability reference

clipboard_read tool

  • Read text, html, rtf, image, or files; auto selects the richest present format (files > image > html > rtf > text). Whole-read limits: 512 KB text/HTML/RTF/files, 5 MB image
  • files returns 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 the notice counts it
  • A macOS clipboard can hold several items; itemCount reports how many, and item (0-based) reads one alone. Without item, 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; the notice says which. Linux and Windows hold one item
  • Returns format, content, byte sizes, complete, representationId, and itemCount; images are base64 PNG with optional width/height. Failures carry format_unavailable (also for an item past the last), 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 and the same item 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 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, 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 (files > image > html > rtf > text, or empty), availableFormats for choosing a read format, and itemCount
  • 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, files across all backends
  • Copied-file paths — files reads each item's public.file-url on macOS, text/uri-list file: 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 innerText line-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_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

VariableDescriptionDefault
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_HTTP_HOSTHostname for HTTP server.127.0.0.1
MCP_HTTP_ENDPOINT_PATHEndpoint path for the HTTP server./mcp
MCP_HTTP_MAX_BODY_BYTESMax 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_MODEHTTP session mode: auto, stateful, or stateless. auto resolves to stateful. This server defaults to stateless — it keeps no per-session state.stateless
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, notice, warning, error).info
LOG_TOOL_FAILURE_PAYLOADSLog 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_ENABLEDEnable OpenTelemetry instrumentation.false
CLIPBOARD_READ_ONLYServe 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

PathPurpose
src/index.tsEntry 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 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.

NPM
@cyanheads/clipboard-mcp-server
Install Command
npm install @cyanheads/clipboard-mcp-server
Runtime: npx
NPM
@cyanheads/clipboard-mcp-server
Install Command
npm install @cyanheads/clipboard-mcp-server
Runtime: npx