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
• 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)
• Returns a typed format_unavailable error when the requested format is not on the clipboard — use clipboard_inspect first to check availability

clipboard_write

Write content to the clipboard, replacing current contents.

• 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
• Returns previousContent — the plain text that was on the clipboard immediately before the write, 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 whatever is currently on the clipboard
• Not registered when CLIPBOARD_READ_ONLY is set — 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)
• 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.

apt install xclip           # Debian/Ubuntu
pacman -S xclip             # 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.