MacOS Clipboard MCP
@xiaoquisme
A simple utility that provides model context protocol (MCP) tools for interacting with the macOS clipboard.
Overview
What is MacOS Clipboard MCP?
MacOS Clipboard MCP is a Model Context Protocol server that exposes tools for reading and writing the macOS clipboard. It is built for developers who want to let AI assistants or MCP-compatible clients copy text to, paste text from, or retrieve images from the system clipboard on macOS.
How to use MacOS Clipboard MCP?
The recommended setup uses uvx with no local install: add an MCP client entry with command uvx and args ["macos-clipboard-mcp"]. Alternatively, clone the repo, run uv sync, and start the server with mcp dev main.py. The server exposes three tools: copy_to_clipboard, paste_from_clipboard, and paste_image_from_clipboard.
Key features of MacOS Clipboard MCP
- Copy arbitrary text strings to the clipboard
- Paste the current clipboard text as a string
- Paste clipboard images (TIFF, PNG, JPEG) as base64-encoded PNG
- Runs entirely on macOS using AppleScript
- Minimal setup with the
uvxone‑command approach
Use cases of MacOS Clipboard MCP
- An AI coding assistant copies generated code to the clipboard for immediate pasting
- A chatbot retrieves text the user previously copied to share with a language model
- An MCP‑enabled workflow extracts an image from the clipboard and processes it elsewhere
FAQ from MacOS Clipboard MCP
What tools does MacOS Clipboard MCP expose?
It exposes three MCP tools: copy_to_clipboard(data: str), paste_from_clipboard() (returns text), and paste_image_from_clipboard() (returns the clipboard image as a base64‑encoded PNG string).
What are the runtime requirements?
Python 3.12 or later and macOS are required. Clipboard operations are implemented via AppleScript, so the server will not function on other operating systems.
How is clipboard interaction implemented under the hood?
The server relies on macOS AppleScript to read from and write to the system clipboard. No external GUI or X11 dependency is needed.
Which image formats can the server handle when pasting an image?
The server supports TIFF, PNG, and JPEG image formats currently in the clipboard. The output is always a base64‑encoded PNG.
How do I configure MacOS Clipboard MCP in my MCP client?
The recommended method adds a clipboard entry with "command": "uvx" and "args": ["macos-clipboard-mcp"]. An alternative method uses "command": "uv" with local folder arguments pointing to a cloned copy of the repository.
