@cyanheads/clipboard-mcp-server

@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

Tools

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

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
clipboard_inspect	List available clipboard formats and byte sizes without reading full content

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 with an auto-generated plain-text fallback (tag-stripped), so paste targets that only accept plain text still receive something useful
• Size limit: 1 MB
• destructiveHint: true — replaces whatever is currently on the clipboard

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
• HTML write with automatic plain-text fallback — stripped and written alongside HTML for apps that only paste plain text
• 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"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "clipboard-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/clipboard-mcp-server:latest"
      ]
    }
  }
}

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

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

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

Docker

docker build -t clipboard-mcp-server .
docker run -p 3010:3010 clipboard-mcp-server

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

Contributing

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

License

Apache 2.0 — see LICENSE.