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
- macOS:
Installation
- Clone the repository:
git clone https://github.com/martinbowling/clipboard-to-supabase-mcp-helper.git
cd clipboard-to-supabase-mcp-helper
- Install dependencies:
npm install
- Create a
.envfile based on.env.example:
SUPABASE_URL=https://<project>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
BUCKET=media
MCP_PORT=3333
- Test your Supabase connection:
npm run test:supabase
- Build the project:
npm run build
- Install as a system service:
For macOS:
npm run install:macos
For Linux:
npm run install:linux
For Windows:
npm run install:windows
Usage
Once installed and running, the helper will:
- Monitor your clipboard for image changes (polling every 300ms)
- Upload any copied images to your Supabase bucket
- 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)
npm start
This runs the MCP server with StdioServerTransport, ideal for command-line usage.
HTTP Mode
npm run start:http
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:
POST http://localhost:3333/mcp
Request body:
{
"id": "1",
"jsonrpc": "2.0",
"method": "tool",
"params": {
"name": "upload_clipboard_image",
"input": {}
}
}
Response:
{
"id": "1",
"jsonrpc": "2.0",
"result": {
"content": [
{
"type": "text",
"text": "https://your-project.supabase.co/storage/v1/object/public/media/clips/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
}
]
}
}
Cleanup Old Files
The helper also provides an MCP endpoint to manually trigger cleanup of old files.
Request body:
{
"id": "1",
"jsonrpc": "2.0",
"method": "tool",
"params": {
"name": "cleanup_old_files",
"input": {
"days": 30
}
}
}
Response:
{
"id": "1",
"jsonrpc": "2.0",
"result": {
"content": [
{
"type": "text",
"text": "Cleanup completed: Deleted 5 files older than 30 days. Failed: 0."
}
]
}
}
The days parameter is optional. If not provided, it will use the value from the RETENTION_DAYS environment variable.
How It Works
- Change Detection: Polls clipboard every 300ms and computes SHA-1 hash of image data
- Deduplication: Only processes new or changed images based on hash comparison
- Platform Adaptation: Uses platform-specific methods to capture clipboard images
- Supabase Integration: Uploads images to your Supabase bucket with unique UUIDs
- MCP Endpoint: Exposes functionality to AI agents via Model Context Protocol
- Automatic Cleanup: Periodically removes images older than the configured retention period (default: 30 days)
Platform-Specific Notes
macOS
- Requires
pngpaste: Install withbrew 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
# Run with live reload (stdio mode)
npm run dev
# Run with live reload (HTTP mode)
npm run dev:http
# Build for production
npm run build
# Run stdio version
npm start
# Run HTTP version
npm run start:http
License
MIT