reel-relay

Forward an Instagram reel to Claude the same way you send it to a friend - then have Claude watch it, research it, and build what it shows.

<p> <a href="https://github.com/siemd2/reel-relay/actions/workflows/tests.yml"><img alt="tests" src="https://github.com/siemd2/reel-relay/actions/workflows/tests.yml/badge.svg"></a> <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue"> <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"> <img alt="MCP" src="https://img.shields.io/badge/Model_Context_Protocol-connector-8A2BE2"> <img alt="Self-hosted" src="https://img.shields.io/badge/self--hosted-yes-orange"> </p>

Ever be doomscrolling reels, hit one with a genuinely good idea - for me it's usually some insane UI demo - and I think "I want Claude to build a demo"... but you can't be bothered to pause, transcribe it, and explain it? So you save it to the graveyard folder you'll never open again.

reel-relay closes that gap. Share the reel to your self-hosted endpoint (a Telegram bot, an iOS Shortcut, or an Instagram DM), and it lands in Claude as a timestamped transcript plus sampled video frames - so Claude can actually "watch" it and you can just say "what's in the reel I just shared?" Then take it further: "research whether this tactic would work for my project" or "build the thing in that reel."

The share gesture you already use 20 times a day - now one of the recipients is Claude.

---

How it works

  phone: Telegram bot  ·  iOS Shortcut  ·  Instagram DM
            │  POST /ingest {url}   (X-Ingest-Secret)
            ▼
   your server (localhost or a free cloud VM)
     ├─ yt-dlp        → download the reel (≤720p mp4)
     ├─ ffmpeg        → ~30 deduplicated keyframes (JPEG, 512px wide)
     ├─ captions →    else Groq whisper-large-v3 → timestamped transcript
     └─ SQLite + frames on disk (the video itself is deleted)
            │
            ▼
   FastMCP server (streamable HTTP, same process)
            │  get_reel() → transcript + frames as MCP images
            ▼
   Claude  (web · desktop · mobile · Claude Code)  via a custom connector

Everything runs in one Python process you host yourself. Claude reaches it as a standard MCP custom connector - the reel's transcript arrives as text and its frames arrive as images, so Claude sees both what's said and what's shown.

Features

• Multiple ways to ingest - forward a reel to a Telegram bot (easiest, works on iOS and Android, no app review), an iOS share-sheet Shortcut, or an Instagram DM webhook.
• Claude actually "watches" the video - timestamped transcript + evenly-sampled, deduplicated frames delivered as MCP image content.
• Three MCP tools tuned so Claude knows to grab "the reel I just shared" with zero ceremony.
• Free transcription via Groq's whisper-large-v3 (falls back to it only when a reel has no captions).
• Runs anywhere - your Mac, a Raspberry Pi, or a free-forever cloud VM. Binds to localhost; you expose it through a tunnel, so no ports are opened to the world.
• Self-healing & tiny - the video is never stored (~0.6 MB of frames per reel), the disk auto-prunes, and the service auto-restarts.

MCP tools

| Tool | What it does | |---|---| | list_recent_reels(limit=10) | Browse recently shared reels (id, title, transcript preview). | | get_reel(reel_id?, include_frames=true, max_frames=10) | Watch a reel - full timestamped transcript + sampled frames. No reel_id → the most recent one (that's "the reel I just shared"). | | get_reel_frames(reel_id?, start_s, end_s) | Zoom into a specific time window for more visual detail. |

---

Quickstart (self-host in ~10 minutes)

Requirements: Python 3.11+, uv, ffmpeg, and a free Groq API key. A cloudflared or Tailscale tunnel to expose it, and a Claude account with custom connectors.

git clone https://github.com/siemd2/reel-relay.git
cd reel-relay

# system deps (macOS shown; Linux: apt install ffmpeg)
brew install ffmpeg uv

uv sync                 # install Python deps
make secrets            # generate INGEST_SECRET + MCP_PATH_TOKEN into .env
# add your Groq key:  echo 'GROQ_API_KEY=gsk_...' >> .env   (or edit .env)
make test               # offline tests - synthesizes a clip with ffmpeg, no network
make dev                # start the server on http://127.0.0.1:8787

Expose it & connect Claude:

# quickest tunnel for testing (random URL, no domain needed):
cloudflared tunnel --url http://localhost:8787

make mcp-url            # prints your connector URL: https://<tunnel-host>/mcp-<token>/mcp

Add that URL in Claude → Settings → Connectors → Add custom connector. No OAuth - the long random path segment is the credential, so treat the URL as a secret.

Share reels to it. Easiest is a Telegram bot — works on iOS and Android, no app review, ~2-minute setup: docs/telegram.md. Prefer something else? An iOS share-sheet Shortcut or the Instagram DM webhook. Then: share/forward a reel → open Claude → "what's in the reel I just shared?"

Run it 24/7 for free (always-on cloud)

Instagram rate-limits datacenter IPs, so the download step wants a "residential-looking" connection - but in practice a free-tier cloud VM works fine for personal volume. The setup the author runs (≈$0/month, survives reboots, independent of your laptop):

1. Free VM - Oracle Cloud Always Free (VM.Standard.E2.1.Micro), or any small Linux box.
2. Deploy - uv sync, drop your .env, install the ops/reel-relay.service systemd unit (systemctl enable --now reel-relay), and add the hourly ops/cleanup.sh cron.
3. HTTPS with no open ports - Tailscale Funnel: tailscale funnel --bg 8787 gives you a permanent https://<machine>.<tailnet>.ts.net URL that routes inbound through Tailscale's edge (the VM never exposes a public port; the app stays bound to localhost). Register that URL + /mcp-<token>/mcp as your connector.

On macOS instead, make launchd-install keeps the server + a Cloudflare tunnel running at login.

---

Configuration

All settings come from environment variables (see .env.example):

| Var | Required | Purpose | |---|---|---| | GROQ_API_KEY | for transcription | Groq key for whisper-large-v3 (free tier). | | INGEST_SECRET | ✅ | Shared secret the /ingest endpoint requires (X-Ingest-Secret header). | | MCP_PATH_TOKEN | ✅ | Long random segment in the MCP URL - the connector's only auth. | | DATA_DIR, HOST, PORT | optional | Storage location and bind address (defaults: ./data, 127.0.0.1, 8787). | | YTDLP_COOKIES_FROM_BROWSER | optional | Reuse a browser's Instagram session for reels that require login. |

make secrets fills the two required secrets for you.

Security

• The server binds 127.0.0.1 only; the tunnel is the sole path in.
• /ingest and the debug endpoints require the X-Ingest-Secret header (constant-time compared).
• The MCP endpoint is guarded by a long random path token - the connector URL is a secret.
• Interactive API docs (/docs, /openapi.json) are disabled since the app faces the internet.
• Videos are never persisted; data/ and .env are gitignored.

Roadmap

• Not sure, will evolve with needs.

Contributions welcome - open an issue or PR.

How it's built

Python 3.11+ · FastAPI · FastMCP (streamable HTTP) · yt-dlp · ffmpeg · Groq whisper-large-v3 · SQLite · uv. One process, no external database, no build step.

License

MIT - do anything you like; self-host your own.