📋 Clayboard MCP

A minimalist, production-ready Model Context Protocol server that gives Claude Desktop seamless access to your system clipboard with automatic history tracking.

✨ Key Features:

• Interactive Waiting - Claude pauses until you copy something
• Automatic History - Last 15 clipboard items tracked automatically
• Cross-Platform - Works on macOS, Windows, and Linux
• Ultra-Safe - No deletion tools, no data loss

🚀 Quick Start

macOS/Linux

cd clipboard-mcp
./setup_mac.sh

Windows

cd clipboard-mcp
.\setup_windows.ps1

Then: Restart Claude Desktop completely (Quit and reopen).

🛠️ The 4 Essential Tools

1. read_clipboard()

Read current clipboard content.

Example prompts:

• "What's in my clipboard?"
• "Read my clipboard and fix the typos"

2. write_clipboard(text)

Write text to clipboard.

Example prompts:

• "Copy this code to my clipboard"
• "Generate a UUID and put it in my clipboard"

3. get_clipboard_history()

View last 15 clipboard items with timestamps.

Example prompts:

• "Show me my clipboard history"
• "What did I copy 5 minutes ago?"
• "Find the API key I copied earlier"

4. wait_for_clipboard_change(timeout) ⭐

Wait for you to copy something (THE GAME CHANGER!).

Example prompts:

• "Wait for me to copy the error"
• "I'll copy it now, hold on"

How it works:

• Takes snapshot of current clipboard
• Polls every 0.5 seconds
• Returns immediately when you copy something new
• Timeout after 60 seconds (configurable up to 120s)

💡 Real-World Examples

Example 1: Interactive Debugging

You: "I'm about to copy an error, wait for it"
Claude: [calls wait_for_clipboard_change()]
You: [copies error from terminal]
Claude: "Got it! The error is caused by..."

Example 2: Time Machine

You: "Show me my clipboard history"
Claude: [shows last 15 items with timestamps]
You: "What was item #3?"
Claude: [reads from history display]

Example 3: Multi-Step Collection

You: "I have 3 API keys to format"
Claude: "Copy the first one, I'll wait"
[wait_for_clipboard_change()]
You: [copies key 1]
Claude: "Got it! Copy the second..."

🧪 Testing

Test Locally (Before Connecting to Claude)

cd clipboard-mcp
uv run --with fastmcp --with pyperclip fastmcp dev clipboard_server.py

You should see all 4 tools listed.

Test in Claude Desktop

1. Restart Claude Desktop completely
2. Type: What tools do you have access to?
3. Look for: read_clipboard, write_clipboard, get_clipboard_history, wait_for_clipboard_change

⚙️ Configuration

Config File Location

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Claude Code: ~/.config/claude-code/mcp_config.json (macOS/Linux)

Configuration

{
  "mcpServers": {
    "clayboard": {
      "command": "/ABSOLUTE/PATH/TO/clipboard-mcp/run_server.sh"
    }
  }
}

Replace /ABSOLUTE/PATH/TO/ with your actual path to run_server.sh!

Get your path:

cd clipboard-mcp
pwd
# Use: /your/actual/path/clipboard-mcp/run_server.sh

Windows Configuration

{
  "mcpServers": {
    "clayboard": {
      "command": "C:\\ABSOLUTE\\PATH\\TO\\clipboard-mcp\\run_server.bat"
    }
  }
}

🔒 Privacy & Security

What Gets Stored (In-Memory Only)

• ✅ Last 15 unique clipboard items
• ✅ Timestamp for each item
• ✅ SHA-256 hash (for duplicate detection)
• ✅ 100-char preview (for logs)

What Does NOT Get Stored

• ❌ No disk persistence (everything in RAM)
• ❌ No network transmission
• ❌ No database writes
• ❌ Logs don't contain full content

Session Lifecycle

• Start MCP: History is empty
• During session: Tracks up to 15 items automatically
• Restart MCP: History cleared (fresh start)

Safety Design

• ✅ No deletion tools (can't lose data accidentally)
• ✅ No clear_clipboard() (won't erase your actual clipboard)
• ✅ No clear_history() (won't delete your session history)
• ✅ History auto-clears on restart (privacy by default)

🐛 Troubleshooting

| Issue | Solution | |-------|----------| | Server not showing in Claude | Restart Claude Desktop completely (Cmd+Q, not just close window) | | Module not found: fastmcp | Run setup script or: pip install fastmcp pyperclip | | Linux clipboard errors | Install xclip: sudo apt install xclip | | Timeout always triggers | Verify clipboard works: pbpaste (Mac) or Get-Clipboard (Windows) | | Wrong path in config | Use absolute path (run pwd in project folder) |

Check Logs

• macOS: ~/Library/Logs/Claude/mcp*.log
• Windows: %APPDATA%\Claude\logs\

📊 Technical Specs

• Language: Python 3.10+
• Dependencies: fastmcp, pyperclip
• File Size: 337 lines (ultra-minimal)
• Tools: 4 essential tools only
• History: 15-item deque (auto-prunes)
• Polling: 500ms intervals
• CPU: < 0.1% idle, < 1% during wait
• Memory: < 5MB typical usage

🎯 Design Philosophy

Minimalism: Only 4 tools. No bloat.

Safety: No deletion tools. Can't lose data.

Simplicity: Does one thing well - clipboard access with history.

Privacy: In-memory only. Auto-clears on restart.

📝 License

MIT License - Free to use, modify, and distribute.

Built with ❤️ for the Claude Desktop community