{
  "markdown": "<div align=\"center\">\n  <h1>@cyanheads/clipboard-mcp-server</h1>\n  <p><b>Read, write, and inspect the system clipboard across macOS, Linux (X11/Wayland), and Windows via MCP. STDIO or Streamable HTTP.</b>\n  <div>3 Tools</div>\n  </p>\n</div>\n\n<div align=\"center\">\n\n[![Version](https://img.shields.io/badge/Version-0.1.8-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/clipboard-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/clipboard-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n</div>\n\n<div align=\"center\">\n\n[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/clipboard-mcp-server/releases/latest/download/clipboard-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=clipboard-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvY2xpcGJvYXJkLW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22clipboard-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fclipboard-mcp-server%22%5D%7D)\n\n[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n</div>\n\n---\n\n## Tools\n\n3 tools for reading, writing, and inspecting the system clipboard:\n\n| Tool | Description |\n|:---|:---|\n| `clipboard_read` | Read clipboard contents in a specified format (text, HTML, RTF, image, or auto-select richest) |\n| `clipboard_write` | Write plain text or HTML to the clipboard, replacing current contents |\n| `clipboard_inspect` | List available clipboard formats and byte sizes without reading full content |\n\n### `clipboard_read`\n\nRead the current clipboard contents in a requested format.\n\n- `auto` mode returns the richest format explicitly present — priority: image > html > rtf > text\n- `image` returns base64-encoded PNG data with pixel dimensions\n- `html` returns raw HTML source as copied from a browser\n- `rtf` returns raw RTF markup\n- `text` returns plain text\n- Size limits: 512 KB for text/HTML/RTF, 5 MB for images (raw bytes before base64 expansion)\n- Returns a typed `format_unavailable` error when the requested format is not on the clipboard — use `clipboard_inspect` first to check availability\n\n---\n\n### `clipboard_write`\n\nWrite content to the clipboard, replacing current contents.\n\n- `text` writes plain text\n- `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`\n- Size limit: 1 MB\n- `destructiveHint: true` — replaces whatever is currently on the clipboard\n\n---\n\n### `clipboard_inspect`\n\nList the formats and byte sizes of what is currently on the clipboard without reading the full content.\n\n- Returns `primaryFormat` — the richest format present (image > html > rtf > text), or `empty`\n- Returns `availableFormats` — all semantic formats present, for deciding which format to pass to `clipboard_read`\n- Returns `rawTypes` — all raw platform type identifiers with byte sizes (UTIs on macOS, TARGETS on X11/Wayland, format names on Windows)\n- Use this before `clipboard_read` to avoid `format_unavailable` errors and to check content size before reading\n\n---\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Unified error handling across all tools\n- Pluggable auth (`none`, `jwt`, `oauth`)\n- Structured logging with optional OpenTelemetry tracing\n- Runs locally via stdio or HTTP from the same codebase\n\nClipboard-specific:\n\n- Cross-platform backend detection at startup — macOS (pbcopy/pbpaste + osascript), Linux X11 (xclip), Linux Wayland (wl-clipboard), Windows (PowerShell 5.1+)\n- Semantic format mapping — platform-native type identifiers (UTIs, TARGETS, Windows format names) mapped to `text`, `html`, `rtf`, `image` across all backends\n- Size-guarded reads and writes — typed `ContentTooLargeError` with byte/limit metadata before content returns\n- Platform-aware HTML writes — macOS and Windows publish HTML plus a stripped plain-text fallback; Linux X11 and Wayland publish `text/html`\n- Image support — macOS and Windows backends decode PNG bytes and return width/height alongside base64 content\n\n---\n\n## Getting started\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n  \"mcpServers\": {\n    \"clipboard-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"bunx\",\n      \"args\": [\"@cyanheads/clipboard-mcp-server@latest\"],\n      \"env\": {\n        \"MCP_TRANSPORT_TYPE\": \"stdio\",\n        \"MCP_LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n  \"mcpServers\": {\n    \"clipboard-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cyanheads/clipboard-mcp-server@latest\"],\n      \"env\": {\n        \"MCP_TRANSPORT_TYPE\": \"stdio\",\n        \"MCP_LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\nOr with Docker:\n\n```json\n{\n  \"mcpServers\": {\n    \"clipboard-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n        \"ghcr.io/cyanheads/clipboard-mcp-server:latest\"\n      ]\n    }\n  }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n**macOS:** No additional tools required — `pbcopy`, `pbpaste`, and `osascript` are built in.\n\n**Linux X11:** `xclip` must be installed.\n\n```sh\napt install xclip           # Debian/Ubuntu\npacman -S xclip             # Arch\n```\n\n**Linux Wayland:** `wl-clipboard` must be installed.\n\n```sh\napt install wl-clipboard    # Debian/Ubuntu\npacman -S wl-clipboard      # Arch\n```\n\n**Windows:** PowerShell 5.1+ (built-in on Windows 10 and later).\n\n---\n\n## Configuration\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |\n| `MCP_HTTP_HOST` | Hostname for HTTP server. | `127.0.0.1` |\n| `MCP_HTTP_ENDPOINT_PATH` | Endpoint path for the HTTP server. | `/mcp` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `notice`, `warning`, `error`). | `info` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n---\n\n## Running the server\n\n### Local development\n\n```sh\n# One-time build\nbun run rebuild\n\n# Run the built server\nbun run start:stdio\n# or\nbun run start:http\n```\n\n### Checks and tests\n\n```sh\nbun run devcheck   # Lint, format, typecheck, security\nbun run test       # Vitest test suite\n```\n\n### Docker\n\n```sh\ndocker build -t clipboard-mcp-server .\ndocker run -p 3010:3010 clipboard-mcp-server\n```\n\n---\n\n## Project structure\n\n| Path | Purpose |\n|:-----|:--------|\n| `src/index.ts` | Entry point — registers tools via `createApp()` |\n| `src/mcp-server/tools/definitions/` | Tool definitions: `clipboard_read`, `clipboard_write`, `clipboard_inspect` |\n| `src/services/clipboard/` | Platform backends (macOS, Linux X11, Wayland, Windows) and service facade |\n| `tests/` | Vitest tests for tools and backends |\n| `skills/` | Agent workflow skills (add-tool, field-test, polish-docs-meta, etc.) |\n\n---\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for the full developer protocol — tool patterns, service patterns, error handling, logging conventions, and the checklist for shipping changes.\n\n---\n\n## Contributing\n\nIssues and pull requests welcome at [github.com/cyanheads/clipboard-mcp-server](https://github.com/cyanheads/clipboard-mcp-server).\n\n---\n\n## License\n\nApache 2.0 — see [`LICENSE`](./LICENSE).\n",
  "bytes": 8756,
  "sha": "d99a53e1bb17010eec0751bedb701b689ca0dc8acea8f2c19a63ecacabeef51c",
  "repo_slug": "cyanheads/clipboard-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_clipboard_mcp_server_12f8acac/readme"
}