Clipboard to Supabase MCP Helper

Clipboard to Supabase MCP Helper

A local agent that monitors the system clipboard, uploads any copied image to Supabase Storage, then writes the public (or signed) URL back to the clipboard.

Features

• Zero-click image hosting: Copy an image, get a URL instantly
• Low latency: Under 800ms from copy to URL
• Cross-platform: Works on macOS, Windows, and Linux
• MCP integration: Expose clipboard image upload as an MCP endpoint
• Auto-start: Configure to run at system startup
• Efficient detection: Hash-based deduplication with low CPU usage

Prerequisites

• Node.js 18+
• Supabase account with Storage enabled
• Platform-specific dependencies:
  • macOS: pngpaste (brew install pngpaste)
  • Windows/Linux: Native OS clipboard access

Installation

1. Clone the repository:

2. Install dependencies:

3. Create a .env file based on .env.example:

4. Test your Supabase connection:

5. Build the project:

6. Install as a system service:

For macOS:

For Linux:

For Windows:

Usage

Once installed and running, the helper will:

1. Monitor your clipboard for image changes (polling every 300ms)
2. Upload any copied images to your Supabase bucket
3. Place the public URL back in your clipboard, ready to paste

Running the Service

The clipboard helper can be run in two modes:

Stdio Mode (Default)

This runs the MCP server with StdioServerTransport, ideal for command-line usage.

HTTP Mode

This runs an Express HTTP server on port 3333 (configurable) with a proper REST API endpoint.

MCP Integration

The helper exposes the following MCP endpoints:

Upload Clipboard Image

With HTTP server mode:

Request body:

Response:

Cleanup Old Files

The helper also provides an MCP endpoint to manually trigger cleanup of old files.

Request body:

Response:

The days parameter is optional. If not provided, it will use the value from the RETENTION_DAYS environment variable.

How It Works

1. Change Detection: Polls clipboard every 300ms and computes SHA-1 hash of image data
2. Deduplication: Only processes new or changed images based on hash comparison
3. Platform Adaptation: Uses platform-specific methods to capture clipboard images
4. Supabase Integration: Uploads images to your Supabase bucket with unique UUIDs
5. MCP Endpoint: Exposes functionality to AI agents via Model Context Protocol
6. Automatic Cleanup: Periodically removes images older than the configured retention period (default: 30 days)

Platform-Specific Notes

macOS

• Requires pngpaste: Install with brew install pngpaste
• Uses LaunchAgents for auto-start

Windows

• Uses PowerShell's System.Windows.Forms.Clipboard for image capture
• Uses Windows Registry for auto-start

Linux

• Uses xclip (X11) or wl-paste (Wayland) for clipboard access
• Uses systemd for auto-start

Development

License

MIT