-
securityF
license-
qualityA bridge between AI assistants like GitHub Copilot and Supabase databases, allowing AI to understand schema, assist with query writing, and provide context-aware suggestions related to your data model.
Last updated -
This server allows you to upload images from your clipboard to Supabase Storage and manage file cleanup via MCP endpoints.
Upload Clipboard Images: Automatically upload images copied to the clipboard to Supabase Storage and return the public URL.
Cleanup Old Files: Manually trigger the deletion of files older than a specified number of days (default: 30 days).
MCP Integration: Expose clipboard functionality as MCP endpoints for AI agents.
Cross-Platform Support: Works on macOS, Windows, and Linux with platform-specific tools.
Can run as an Express HTTP server that exposes MCP endpoints via REST API for programmatic image uploading and file management.
Provides platform-specific integration for clipboard monitoring on Linux using xclip (X11) or wl-paste (Wayland), with systemd for auto-start functionality.
Provides platform-specific integration for clipboard monitoring and image capture on macOS using pngpaste, with LaunchAgents for auto-start functionality.
Automatically uploads clipboard images to Supabase Storage and returns public URLs, with features for managing stored files including automatic cleanup of old files.
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
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 pngpasteUses 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
local-only server
The server can only run on the client's local machine because it depends on local resources.
A local agent that monitors your system clipboard, automatically uploads copied images to Supabase Storage, and replaces the clipboard content with the public URL for immediate sharing.
Related MCP Servers
- -securityFlicense-qualityA multi-tenant service that automatically monitors Supabase database changes, generates OpenAI embeddings, and maintains synchronized vector search capabilities for each tenant's projects.Last updated -
- -securityFlicense-qualityA Model Context Protocol server that integrates with Supabase, allowing AI assistants to access and manipulate store data through tools for product searching, filtering, and analysis.Last updated -
- -securityAlicense-qualityA high-performance server that provides clipboard access for AI assistants, specifically designed to solve the VSCode + WSL2 image clipboard limitation when using Claude.Last updated -23MIT License