Skillget

reel-relay

mcp
Guvenlik Denetimi
Basarisiz
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Basarisiz
  • rm -rf — Recursive force deletion command in ops/cleanup.sh
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Share an Instagram reel to Claude — watch, research, and build what it shows. Self-hosted MCP connector (yt-dlp + ffmpeg + Groq Whisper).

README.md

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.

Python 3.11+ License: MIT MCP Self-hosted

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 (an iOS Shortcut in your share sheet, 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

  iPhone share sheet / 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

  • Two ways to ingest - an iOS Shortcut in your share sheet, or (more robust) share a reel to a bot Instagram account and let Meta's DM webhook push it straight to your server (setup).
  • 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.

Put it in your share sheet: follow shortcuts/README.md to build the
2-minute "Send to Claude" iOS Shortcut. Then: Instagram → any reel → Share → Send to Claude
→ 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

  • Instagram DM webhook ingestion (built). Share a reel to a bot Instagram account; Meta delivers a signed CDN URL via webhook - no scraping, no share sheet, works from any cloud IP. The most reliable path. Setup: docs/instagram-webhook.md.
  • Per-reel chat memory & tags · a tiny web dashboard · TikTok / YouTube Shorts support.

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.

Yorumlar (0)

Sonuc bulunamadi