reel-relay

# 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](https://modelcontextprotocol.io) 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](docs/telegram.md) (easiest, works on iOS *and* Android, no app review), an [iOS share-sheet Shortcut](shortcuts/README.md), or an [Instagram DM webhook](docs/instagram-webhook.md). - **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`](https://docs.astral.sh/uv/), `ffmpeg`, and a free [Groq API key](https://console.groq.com). A [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) or [Tailscale](https://tailscale.com) tunnel to expose it, and a Claude account with custom connectors. ```bash 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:** ```bash # 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](docs/telegram.md). Prefer something else? An [iOS share-sheet Shortcut](shortcuts/README.md) or the [Instagram DM webhook](docs/instagram-webhook.md). 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](https://www.oracle.com/cloud/free/) (`VM.Standard.E2.1.Micro`), or any small Linux box. 2. **Deploy** - `uv sync`, drop your `.env`, install the [`ops/reel-relay.service`](ops/reel-relay.service) systemd unit (`systemctl enable --now reel-relay`), and add the hourly [`ops/cleanup.sh`](ops/cleanup.sh) cron. 3. **HTTPS with no open ports** - [Tailscale Funnel](https://tailscale.com/kb/1223/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`](.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](https://fastapi.tiangolo.com) · [FastMCP](https://github.com/jlowin/fastmcp) (streamable HTTP) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · `ffmpeg` · [Groq](https://groq.com) `whisper-large-v3` · SQLite · [`uv`](https://docs.astral.sh/uv/). One process, no external database, no build step. ## License [MIT](LICENSE) - do anything you like; self-host your own.