Tools

3 tools for reading, writing, and inspecting the system clipboard:

clipboard_read

Read the current clipboard contents in a requested format.

• auto mode returns the richest format explicitly present — priority: image > html > rtf > text
• image returns base64-encoded PNG data, with pixel dimensions on every platform whenever the capture carries a readable PNG header
• html returns raw HTML source as copied from a browser
• rtf returns raw RTF markup
• text returns plain text
• Size limits: 512 KB for text/HTML/RTF, 5 MB for images (raw bytes before base64 expansion)
• Content above the size limit is retrieved in slices with offset/limit instead of erroring outright: pass both to read a bounded window (limit is at least 4 and clamped to the format's size limit) and follow the returned nextOffset until complete is true. Every response carries totalByteSize and complete; text/HTML/RTF slices never split a multi-byte UTF-8 sequence. Omitting both reads the whole payload as before, still bounded by the size limit
• Returns a typed format_unavailable error when the requested format is not on the clipboard — use clipboard_inspect first to check availability
• Returns a typed content_too_large error only when no offset/limit was given and the content exceeds the size limit; the recovery hint points at the slicing parameters above

clipboard_write

Write content to the clipboard, replacing current contents — or clear it.

• text writes plain text
• 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, so a following clipboard_inspect reports primaryFormat: "empty". It returns cleared: true, byteSize: 0, and no format. On Linux X11 this needs xsel alongside xclip — see Prerequisites
• Supply exactly one of content or clear: true. Omitting both, sending an empty content, or combining the two is rejected as invalid arguments rather than silently writing a zero-byte representation
• Returns previousContent — the plain text that was on the clipboard immediately before the write or clear, so an unintended overwrite can be undone by writing it back. Absent when the clipboard was empty, held no text representation, or its text exceeded the 512 KB read limit
• Size limit: 1 MB
• destructiveHint: true — replaces or removes whatever is currently on the clipboard
• Not registered when CLIPBOARD_READ_ONLY is set, which gates clearing along with writing — see Configuration

clipboard_inspect

List the formats and byte sizes of what is currently on the clipboard without reading the full content.

• Returns primaryFormat — the richest format present (image > html > rtf > text), or empty
• Returns availableFormats — all semantic formats present, for deciding which format to pass to clipboard_read
• Returns rawTypes — all raw platform type identifiers with byte sizes (UTIs on macOS, TARGETS on X11/Wayland, format names on Windows). An entry whose size could not be measured carries measurementFailed: true and no bytes, so a failed measurement is never reported as a zero-byte representation
• Returns a typed inspect_unreadable error when the platform helper's output cannot be read, instead of reporting an empty clipboard
• Use this before clipboard_read to avoid format_unavailable errors and to check content size before reading

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Structured logging with optional OpenTelemetry tracing
• Runs locally via stdio or HTTP from the same codebase

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
• Size-guarded reads and writes — typed ContentTooLargeError with byte/limit metadata before content returns
• Platform-aware HTML writes — macOS and Windows publish HTML plus a stripped plain-text fallback; Linux X11 and Wayland publish text/html
• Image support — macOS and Windows backends decode PNG bytes and return width/height alongside base64 content

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

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

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

Development guide

See CLAUDE.md for the full developer protocol — tool patterns, service patterns, error handling, logging conventions, and the checklist for shipping changes.

Contributing

Issues and pull requests welcome at github.com/cyanheads/clipboard-mcp-server.

License

Apache 2.0 — see LICENSE.