beeper-mcp-file-proxy

Stdio-to-HTTP proxy for Beeper Desktop MCP (Model Context Protocol) that adds file attachment support.

Beeper Desktop exposes an MCP server over Streamable HTTP, but Claude Code only supports stdio transports. This proxy bridges the two and injects a send_file tool that lets Claude send images, videos, audio, and documents to any chat.

Install

Run directly with npx (no install needed):

npx beeper-mcp-file-proxy

Or install globally:

npm install -g beeper-mcp-file-proxy

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BEEPER_ACCESS_TOKEN | Yes | - | Your Beeper Desktop API access token. Find it in Beeper Desktop: Settings > Advanced > API Access Token. | | BEEPER_URL | No | http://localhost:23373 | Base URL for the Beeper Desktop API. |

Claude Code Setup

Add to your ~/.claude.json (or project .claude/settings.json) under mcpServers:

{
  "mcpServers": {
    "beeper": {
      "command": "npx",
      "args": ["beeper-mcp-file-proxy"],
      "env": {
        "BEEPER_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "beeper": {
      "command": "beeper-mcp-file-proxy",
      "env": {
        "BEEPER_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

How It Works

1. Stdio-to-HTTP bridge: Reads JSON-RPC messages from stdin, forwards them to Beeper Desktop's Streamable HTTP endpoint (/v0/mcp), and writes responses back to stdout.

2. SSE parsing: Beeper responds with Server-Sent Events (SSE). The proxy extracts data: lines and converts them back to JSON-RPC for Claude Code.

3. send_file tool injection: When Claude calls tools/list, the proxy appends the send_file tool to the response. When send_file is invoked:

   • Uploads the file to Beeper via POST /v1/assets/upload (multipart form)
   • Sends a message with the attachment via POST /v1/chats/{chatID}/messages
   • Beeper Desktop handles E2EE transparently

Tools Added

send_file

Send a file (image, video, audio, document) to a chat.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | chatID | string | Yes | Unique identifier of the chat. | | filePath | string | Yes | Absolute path to the file on disk. | | text | string | No | Caption/text to send with the file. | | replyToMessageID | string | No | Message ID to reply to. |

Supported formats: MP4, MOV, AVI, WebM, JPEG, PNG, GIF, WebP, HEIC, PDF, DOC, ZIP, MP3, OGG, WAV, M4A, and any other file type (sent as application/octet-stream).

Why This Exists

Beeper Desktop's built-in MCP server does not support file attachments. This proxy adds that capability by using Beeper's REST API for uploads and message sending.

Feature request: beeper/desktop-api-js#35

License

MIT