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

• 🔍 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

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

# 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

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

The server provides 9 MCP tools for clipboard management:

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"
}

Get the most recent clipboard items with optional filtering.

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

Get clipboard items from a specific application.

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

Copy a specific history item back to the current clipboard.

{
  "item_id": 1234
}

Pin or unpin clipboard items for persistence.

{
  "item_id": 1234
}

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"
}

Get usage statistics about your clipboard history.

{}

Get the full content of a specific clipboard item.

{
  "item_id": 1234
}

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.

➡️ View the Example System Prompt

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.

• 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

• 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)

# 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

# Run tests
./run_test.sh

# Clean dependencies
go mod tidy

├── 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

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

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

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