io.github.cyanheads/clipboard-mcp-server

---

Overview

The system clipboard across macOS, Linux (X11/Wayland), and Windows. Read, write, and inspect text, HTML, RTF, and image content from any MCP client. Runs as a stdio process or a local Streamable HTTP server.

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

• auto returns the richest format explicitly present — priority: image > html > rtf > text; format requests a specific one instead
• Size limits: 512 KB for text/HTML/RTF, 5 MB for images (raw bytes before base64 expansion)
• Content above the limit reads via offset/limit slicing — pass both to read a bounded window (limit is at least 4, clamped to the format's size limit) and follow the returned nextOffset until complete is true
• image returns base64-encoded PNG data, with width/height whenever the capture carries a readable PNG header
• Typed errors: format_unavailable when the requested format isn't on the clipboard, content_too_large when no offset/limit was given and content exceeds the size limit

---

clipboard_write _tool

• Exactly one of content or clear: true — an empty content, both, or neither is rejected as invalid input
• format: "html" writes HTML; macOS and Windows also publish an auto-generated, tag-stripped plain-text fallback, while Linux X11 and Wayland publish only text/html
• clear: true removes every representation instead of writing (needs xsel alongside xclip on Linux X11) and returns cleared: true, byteSize: 0, no format
• Returns previousContent — the plain text on the clipboard immediately before the write or clear, for undoing an unintended overwrite — absent when the clipboard was empty, held no text representation, or that text exceeded the 512 KB read limit
• Size limit: 1 MB, past which a typed content_too_large error is returned
• Not registered when CLIPBOARD_READ_ONLY is set, which gates clearing along with writing

---

clipboard_inspect _tool

• Returns primaryFormat (richest present — image > html > rtf > text — or empty) and availableFormats, the formats available to pass to clipboard_read
• Returns rawTypes — every raw platform type identifier with byte size (UTIs on macOS, TARGETS on X11/Wayland, format names on Windows); an entry whose size couldn't be measured carries measurementFailed: true and no bytes, never a false zero
• Typed inspect_unreadable error when the platform helper's output cannot be read, instead of reporting an empty clipboard

---

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 (pbcopy/pbpaste + osascript), 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; Linux X11 and Wayland publish text/html only
• Image support — macOS and Windows backends decode PNG bytes and return width/height alongside base64 content

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
• Undo support — clipboard_write returns previousContent so an unintended overwrite can be reverted
• Discriminated failure — format_unavailable, content_too_large, and inspect_unreadable are typed reasons with recovery hints, not generic errors

---

Getting started

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "clipboard-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/clipboard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "clipboard-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/clipboard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun 1.4.0+ or Node.js 24+.

macOS: No additional tools required — pbcopy, pbpaste, and osascript are 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).

---

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
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false
CLIPBOARD_READ_ONLY	Serve the clipboard read-only. When true, clipboard_write is not registered — absent from tools/list and uncallable, though still shown in a disabled state on the manifest and landing page. 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

Local development

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Checks and tests

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite

---

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 — no try/catch in tool logic
• Use ctx.log for request-scoped logging
• No Docker — this server needs direct host OS access (pbcopy/pbpaste, 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.