chew-z/maccy-go

Maccy Clipboard MCP Server

A Go-based MCP (Model Context Protocol) server that provides programmatic access to your Maccy clipboard history on macOS.

Features

• 🔍 Search clipboard history with text patterns or regex
• 📋 Retrieve recent items with flexible filtering
• 📱 Filter by application to find items from specific apps
• 📌 Pin/unpin items for persistence
• 📤 Export history to JSON, CSV, or TXT formats
• 📊 Get usage statistics and top applications
• 🔧 Fully configurable via CLI arguments and environment variables

Quick Start

Prerequisites

• macOS (required for Maccy integration)
• Maccy clipboard manager installed and running
• Go 1.19+ (for building from source)

Installation

# Clone the repository
git clone https://github.com/your-username/maccy-clipboard-mcp-go.git
cd maccy-clipboard-mcp-go

# Build the server
go build -o bin/maccy-clipboard-mcp main.go

# Run the server
./bin/maccy-clipboard-mcp

Configuration

Configure the server using CLI arguments or environment variables:

# CLI Arguments
./bin/maccy-clipboard-mcp -search-limit 20 -recent-limit 15 -readonly

# Environment Variables (higher priority)
export MACCY_SEARCH_LIMIT=25
export MACCY_RECENT_LIMIT=20
export MACCY_EXPORT_FORMAT=csv
./bin/maccy-clipboard-mcp

Available Options

MCP Tools

The server provides 9 MCP tools for clipboard management:

1. search_clipboard

Search clipboard history by text pattern or regex.

{
  "query": "password",
  "limit": 5,
  "use_regex": false,
  "app_filter": "com.apple.Safari",
  "since": "2025-01-01T00:00:00Z"
}

2. get_recent_items

Get the most recent clipboard items with optional filtering.

{
  "limit": 10,
  "application": "com.apple.Terminal",
  "exclude_images": true
}

3. get_items_by_app

Get clipboard items from a specific application.

{
  "application": "com.apple.Safari",
  "limit": 15
}

4. copy_to_clipboard

Copy a specific history item back to the current clipboard.

{
  "item_id": 1234
}

5. pin_item / unpin_item

Pin or unpin clipboard items for persistence.

{
  "item_id": 1234
}

6. export_history

Export clipboard history to a local file.

{
  "file_path": "/tmp/clipboard_export.json",
  "format": "json",
  "since": "2025-01-01T00:00:00Z",
  "until": "2025-01-31T23:59:59Z"
}

7. get_clipboard_stats

Get usage statistics about your clipboard history.

{}

8. get_item_content

Get the full content of a specific clipboard item.

{
  "item_id": 1234
}

System Prompt

To effectively guide a Large Language Model (LLM) on how to use these tools, a system prompt is crucial. It provides the LLM with a clear understanding of its role, the available tools, and the optimal strategy for interacting with the user and the Maccy clipboard history.

We provide an example system prompt that you can use as a starting point.

This prompt is designed to instruct the model to follow a safe and logical workflow: first searching for items, then asking the user for confirmation, and only then performing an action like copying to the clipboard.

Architecture

Performance Optimizations

• Shared Database Connection: Single connection eliminates per-request overhead (9 connections → 1 shared)
• Pure Go SQLite: Uses modernc.org/sqlite for CGO-free operation
• Efficient Content Handling: Proper byte/string conversion for all content types

Database Integration

• Location: ~/Library/Containers/org.p0deje.Maccy/Data/Library/Application Support/Maccy/Storage.sqlite
• Schema: Direct access to ZHISTORYITEM and ZHISTORYITEMCONTENT tables
• Timestamps: Handles Apple Core Data format (seconds since 2001-01-01)

Development

Building

# Build for development
go build -o bin/maccy-clipboard-mcp main.go

# Run with custom configuration
./bin/maccy-clipboard-mcp -search-limit 50 -recent-limit 100

# Build with version info
go build -ldflags "-X main.version=1.0.0" -o bin/maccy-clipboard-mcp main.go

Testing

# Run tests
./run_test.sh

# Clean dependencies
go mod tidy

Project Structure

├── main.go              # Entry point
├── server/
│   ├── server.go        # MCP server setup, 9 tool definitions
│   ├── handlers.go      # Tool implementation logic
│   ├── database.go      # SQLite interface to Maccy DB
│   ├── clipboard.go     # macOS clipboard operations
│   └── config.go        # Configuration management
├── bin/                 # Built executables
└── README.md           # This file

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Maccy - Excellent clipboard manager for macOS
• MCP Go - Go implementation of the Model Context Protocol