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

📦 Installation

Prerequisites

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

Steps

1. Clone the repository:

git clone https://github.com/martinbowling/clipboard-to-supabase-mcp-helper.git
cd clipboard-to-supabase-mcp-helper

2. Install dependencies:

npm install

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

SUPABASE_URL=https://<project>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
BUCKET=media
MCP_PORT=3333

4. Test your Supabase connection:

npm run test:supabase

5. Build the project:

npm run build

6. Install as a system service:

• For macOS:

npm run install:macos

• For Linux:

npm run install:linux

• For Windows:

npm run install:windows

💻 Usage Examples

Basic 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

Advanced Usage

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.

🔧 Technical Details

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)

📚 Documentation

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

# 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