clipboard-mcp-server

<div align="center"> <h1>@cyanheads/clipboard-mcp-server</h1> <p><b>Read, write, and inspect the system clipboard across macOS, Linux (X11/Wayland), and Windows via MCP. STDIO or Streamable HTTP.</b> <div>3 Tools</div> </p> </div> <div align="center">

</div> <div align="center">

</div>

---

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, 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

| 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 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.