Maccy Clipboard

You can run a lightweight MCP server that exposes your Maccy clipboard history to Claude and other AI assistants. This lets you search, retrieve, and manage clipboard items through natural conversation while keeping control of your data on your macOS system.

How to use

Start the MCP server locally and connect it to Claude Desktop or another MCP-compatible client. You will be able to search your clipboard history, fetch recent items with full content, view images, pin items, export history, and filter results by application. All actions are performed through natural language queries in your client.

How to install

Prerequisites: install on macOS with Maccy, and have Node.js 16-plus installed on your system.

Easy Installation (Recommended)

1. Download the maccy-clipboard-mcp.dxt file from the project assets.

2. Double-click the .dxt file to open it in Claude Desktop.

3. Claude Desktop will automatically install and configure the MCP server.

4. Restart Claude Desktop.

Manual Installation

If you encounter issues with the .dxt installation, you can run the server locally from source.

1. Clone the repository and navigate into the project folder.

2. Install dependencies.

3. Configure Claude Desktop to load the MCP server by adding the following snippet to your Claude Desktop configuration file:

{
  "mcpServers": {
    "maccy-clipboard": {
      "command": "node",
      "args": ["/path/to/maccy-clipboard-mcp/server/index.js"]
    }
  }
}

Additional guidance

Restart Claude Desktop after making configuration changes. If you run into issues, verify that Node.js is installed and that Claude Desktop is not using its built-in Node.js for MCP unless you want to. Detailed troubleshooting steps are below.

Security notes

This MCP server gives Claude access to your clipboard history, which may include sensitive data. Use this tool only if you are comfortable with the potential data exposure and have considered your security requirements. All data stays local on your machine, and the server’s default access is read-only for everything except pin/unpin operations.

Troubleshooting

Required Node.js configuration if the extension fails to load: disable Claude Desktop's built-in Node.js and use your system Node.js installation.

Steps to disable Claude Desktop’s built-in Node.js and use the system version:

1. Install Node.js LTS from nodejs.org
2. Claude Desktop > Settings > Extensions > Advanced Settings
3. Disable "Use Built-in Node.js for MCP"
4. Restart Claude Desktop

Notes

All data is stored locally on your machine. The MCP server has read-only access by default (except for pin and unpin actions). Large exports are written to local files to avoid MCP size limits.

Available tools

search_clipboard

Search clipboard history by text patterns with optional filters such as application or time range.

get_recent_items

Retrieve the most recent clipboard items with full content and image support.

copy_to_clipboard

Copy a selected item back to the system clipboard, supporting both text and image content.

pin_item

Pin a useful clipboard item to keep it readily accessible.

unpin_item

Remove a previously pinned item from the pinned list.

export_history

Export the clipboard history to a local file in JSON, CSV, or TXT formats.

get_clipboard_stats

View usage statistics and trends for clipboard activity.

get_items_by_app

Filter clipboard items by the originating application, with optional image support.