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

• 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 (Linux backends read them from the PNG header)

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

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 the manifest and tools/list and uncallable, but shown as disabled on the 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

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