media-mcp

Soziale Medien direkt zur Hand. 31 Tools für Twitter/X, YouTube, Instagram und Videoverarbeitung – von Claude Desktop, Claude Code oder jedem MCP-Client. 100 % Open Source.

Zeig auf einen Tweet und du bekommst den vollständigen Text, Metriken und die Videotranskription. Gib eine YouTube-URL an und erhalte das Transkript. Wirf einen Instagram-Reel hinein und lade die Medien herunter plus Audio-Transkription. Die gesamte Transkription läuft lokal über Whisper – kein Audio verlässt deinen Rechner.

Die These: Ohren immer, Augen nur wenn die Ohren versagen

Kleine Whisper-Modelle sind großartig im Hören, aber schlecht im Lesen. Sie hören ungewöhnliche Namen falsch. Sie können Text auf dem Bildschirm nicht transkribieren. Sie überspringen eingebrannte Untertitel. Für 90 % der Fragen zu einem Video spielt das keine Rolle – der Kern reicht aus.

Aber wenn ein Nutzer fragt „Wie lautet der Installationsbefehl in diesem Reel?" oder „Wie heißt der Handle, den er gezeigt hat?", liefert die Transkription allein selbstbewusst die falsche Antwort. Die URL war auf dem Bildschirm. Das Eigennamen wurde in der Untertitelung ausgeschrieben. Whisper hat nichts davon gesehen.

media-mcp transkribiert mit Token-genauer Konfidenz über whisper-cli -ojf und markiert Unsicherheitszonen (wo Whisper zugibt, geraten zu haben) und demonstrative Phrasen („besuchen Sie unsere", „dieser Befehl", „in der Bio" – starke Signale, dass auf Bildschirminhalte verwiesen wird). Die LLM liest diese Marker und entscheidet, ob sie get_video_frames_at für die spezifischen Zeitstempel aufrufen soll, die eine visuelle Überprüfung benötigen. Frames werden nur dann erzeugt, wenn sie nötig sind. Das eigene Sehvermögen der LLM übernimmt das Lesen – kein OCR, kein zweites Modell.

Ergebnis: Der Agent hat Ohren bei jedem Video, Augen nur dort, wo die Ohren versagen. Minimale Frames, maximale Genauigkeit.

Related MCP server: youtube-mcp

Was es tut

• Ruft Tweets, Threads, Profile, Follower, Trends und Suchergebnisse von Twitter/X ab (26 Tools über die TwitterAPI.io-REST-API, mit optionaler Xquik-Unterstützung für überlappende Lese-Tools)

• Transkribiert Video-Audio lokal mit whisper-cli – lädt Medien herunter, extrahiert Audio mit ffmpeg, führt Whisper auf deiner Hardware aus und liefert Token-genaue Konfidenz und Treffer für demonstrative Phrasen, damit die LLM weiß, wo der Audio-Kanal unzuverlässig ist

• Lädt Instagram-Beiträge, Reels und Karussells in lokale Ordner über eine selbst gehostete Cobalt-Instanz herunter

• Extrahiert Frames aus jeder Video-URL mit konfigurierbarer FPS – oder präzise an einem Array von Zeitstempeln über get_video_frames_at (cache-bewusst, kein erneuter Download bei Folgeabfragen)

• Überwacht Twitter-Nutzer in Echtzeit und filtert Tweets nach Schlüsselwortregeln

• Cacht heruntergeladene Videos in ~/.media-mcp/cache/videos/ (sha256-der-URL-Schlüssel, 24h TTL), sodass Transkription + Frame-Suche für dasselbe Video in einem Download erfolgen

So funktioniert es

Die LLM scrapt nie HTML oder parst DOM. Jedes Tool ruft eine zweckgebaute API auf und liefert strukturierten, LLM-bereiten Text zurück.

Für Textdaten (Tweets, Profile, Trends): ein REST-Aufruf an TwitterAPI.io standardmäßig, geparst in formatierte Ausgabe. Setze TWITTER_BACKEND=xquik mit XQUIK_API_KEY, um Xquik für überlappende Lese-Tools zu verwenden.

Für Transkription (Tweet-Videos, YouTube, Instagram-Reels): Die Pipeline lädt Medien in den gemeinsamen Cache herunter, extrahiert Audio mit ffmpeg (16-kHz-Mono-WAV), transkribiert mit whisper-cli unter Verwendung von -ojf (output-json-full), um Token-genaue Wahrscheinlichkeiten zu erhalten, und liefert dann ein LLM-lesbares Transkript mit Inline-⟨token p=0.XX⟩-Markern plus Zusammenfassungsblöcken für Unsicherheitszonen und demonstrative Phrasen. Bei YouTube werden zuerst Untertitel versucht (sofort) – Whisper ist nur der Fallback.

Für visuelle Daten (Instagram-Bilder, Video-Frames): Medien werden in einen lokalen Ordner heruntergeladen und absolute Dateipfade werden zurückgegeben, damit die LLM sie direkt mit Vision lesen kann. Die Frame-Extraktion hat zwei Modi: Bulk (extract_video_frames mit konfigurierbarer FPS) und Präzision (get_video_frames_at – ein JPG pro Zeitstempel, für gezielte Überprüfung transkriptionsunsicherer Momente).

Pipeline

URL ──► Detect platform
             │
             ├── Twitter ──► TwitterAPI.io or Xquik REST ──► structured text
             │                     │
             │               has video? ──► cache ──► ffmpeg ──► whisper-cli -ojf
             │                                                         │
             │                                       transcript + confidence markers
             │
             ├── YouTube ──► try captions (instant)
             │                     │
             │               no captions? ──► yt-dlp ──► ffmpeg ──► whisper-cli -ojf
             │
             ├── Instagram ──► Cobalt API ──► download to cache
             │                     │
             │               has video? ──► ffmpeg ──► whisper-cli -ojf
             │
             ├── Video URL ──► cache ──► ffmpeg -vf fps=N ──► frame JPGs
             │
             └── Video URL + timestamps[] ──► cache ──► ffmpeg -ss each ──► one JPG per timestamp
                 (for targeted verification when transcription uncertainty demands it)

Transkription enthält immer Token-genaue Konfidenz und Scans auf demonstrative Phrasen. Die LLM leitet zur Frame-Extraktion weiter, wenn diese Signale es erfordern.

Alle Transkription ist lokal. Alle temporären Dateien werden bereinigt. Heruntergeladene Videos liegen 24 Stunden in einem gemeinsamen Cache (~/.media-mcp/cache/videos/), sodass Folgeaufrufe für dieselbe URL nicht erneut herunterladen. Die LLM erhält strukturierten Text oder Dateipfade – nie rohes API-JSON.

Designprinzipien

1. Strukturierte Daten, kein Scraping. Jedes Tool ruft eine zweckgebaute API auf. Kein HTML-Parsing, keine fragilen Selektoren, keine Browser-Automatisierung.

2. Nur lokale Transkription. Audio verlässt nie den Rechner. Whisper läuft auf lokaler Hardware.

3. Untertitel zuerst, Whisper zweitens. Verbrenne keine Rechenleistung, wenn die Plattform die Arbeit bereits erledigt hat.

4. Ein Tool, eine Aufgabe. Keine Mehrzweck-Tools mit Modus-Flags. Jedes Tool macht genau eine Sache.

5. Dateipfade für visuelle Inhalte. Gib absolute Pfade zurück, damit die LLM Bilder direkt sehen kann.

6. Ohren immer, Augen nur wenn die Ohren versagen. Transkription ist billig; Vision-Tokens sind teuer. Die LLM sieht Frames nur an Zeitstempeln, an denen Whisper zugibt, unsicher zu sein, oder an denen der Sprecher explizit auf etwas auf dem Bildschirm verweist. Nicht mit 1 fps. Nicht als Keyframes. Genau dort, wo Genauigkeit es tatsächlich braucht.

7. Keine OCR-Ebene. Claudes Vision liest die Frames direkt. Ein Modell, das alle multimodalen Überlegungen übernimmt, schlägt eine Zwei-Modell-Naht, bei der OCR und Vision konkurrieren.

Siehe SKILL.md für die vollständigen Pipeline-Details, die Tool-Referenz und Anti-Patterns.

Erste Schritte

npx (am schnellsten)

TWITTER_API_KEY=your_key npx media-mcp

Oder registriere es mit Claude Code in einem Befehl:

claude mcp add media-mcp -e TWITTER_API_KEY=your_key -- npx media-mcp

Das Whisper-Basismodell wird automatisch bei der ersten Transkription in ~/.media-mcp/models/ heruntergeladen. ffmpeg, whisper-cli und yt-dlp müssen weiterhin installiert sein (siehe Voraussetzungen).

Docker

docker run -i --rm \
  -e TWITTER_API_KEY=your_key \
  -v media-mcp-data:/data \
  ghcr.io/woosal1337/media-mcp

Das Image bündelt ffmpeg, yt-dlp und whisper-cli. Modelle und der Video-Cache bleiben im /data-Volume erhalten.

Aus dem Quellcode

git clone https://github.com/woosal1337/media-mcp.git
cd media-mcp
npm install && npm run build

Lade das Whisper-Modell herunter (optional – übersprungene Modelle werden bei Bedarf abgerufen):

mkdir -p models
curl -L -o models/ggml-base.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin

Erstelle .env:

cp .env.example .env
# Edit with your keys:
# TWITTER_API_KEY=your_twitterapi_io_key
# Optional Xquik backend for overlapping read tools:
# TWITTER_BACKEND=xquik
# XQUIK_API_KEY=your_xquik_key
# XQUIK_BASE_URL=https://xquik.com/api/v1
# WHISPER_MODEL_PATH=/absolute/path/to/models/ggml-base.bin
# COBALT_API_URL=http://localhost:9000       (optional, for Instagram)
# COBALT_API_KEY=your_cobalt_key             (optional)
# CLOUDFLARE_ACCOUNT_ID=your_account_id     (optional, for fetch_markdown)
# CLOUDFLARE_API_TOKEN=your_api_token       (optional, for fetch_markdown)

Voraussetzungen

Konfiguration

Claude Code

Füge zu ~/.claude/settings.json hinzu:

{
  "mcpServers": {
    "media-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/media-mcp/dist/index.js"],
      "env": {
        "TWITTER_API_KEY": "your_key",
        "TWITTER_BACKEND": "twitterapi",
        "WHISPER_MODEL_PATH": "/absolute/path/to/media-mcp/models/ggml-base.bin",
        "COBALT_API_URL": "http://localhost:9000",
        "COBALT_API_KEY": "your_cobalt_key",
        "CLOUDFLARE_ACCOUNT_ID": "your_account_id",
        "CLOUDFLARE_API_TOKEN": "your_api_token"
      }
    }
  }
}

Claude Desktop

Füge zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder %APPDATA%\Claude\claude_desktop_config.json (Windows) hinzu – gleiche Struktur wie oben.

Umgebungsvariablen

Tools

Twitter/X – 26 Tools

TwitterAPI.io ist das Standard-Backend für alle Twitter/X-Tools. Setze TWITTER_BACKEND=xquik mit XQUIK_API_KEY, um die überlappenden Lese-Tools stattdessen an Xquik zu senden. Beide Backends liefern dieselbe Tool-Ausgabe, sodass sich sonst nichts ändert.

Ein Nur-TwitterAPI.io-Tool wirft einen klaren Fehler, wenn du TWITTER_BACKEND=xquik ohne TWITTER_API_KEY ausführst. Setze beide Schlüssel, um jedes Tool zu nutzen und trotzdem über Xquik zu lesen.

Tweets abrufen

Profile abrufen

Echtzeit-Überwachung

YouTube — 1 Tool

Instagram — 1 Tool

Cloudflare — 1 Tool

Video — 2 Tools

So funktioniert die Transkription

video → cache → ffmpeg -ar 16000 -ac 1 → audio.wav → whisper-cli -ojf → audio.wav.json
                                                                            │
                                                                            ▼
                                                         parse per-token probabilities
                                                                            │
                                                                            ▼
                                        transcript with ⟨token p=0.XX⟩ markers
                                        + Uncertainty zones summary (midpoint_s each)
                                        + Demonstrative phrases block (midpoint_s each)

1. Video wird nach ~/.media-mcp/cache/videos/<sha256>.mp4 heruntergeladen (wiederverwendet, falls vorhanden, <24h alt)

2. ffmpeg extrahiert Audio als 16-kHz-Mono-WAV

3. whisper-cli transkribiert lokal mit -ojf (output-json-full) — JSON enthält p-Werte pro Token

4. Token unter p=0,5 werden zu zusammenhängenden Bereichen (≤150ms Lücke) zusammengeführt und als Unsicherheitszonen gemeldet

5. Der Segmenttext wird auf demonstrative Phrasen durchsucht, die typischerweise auf Bildschirminhalte verweisen

6. Das LLM erhält segmentweises Transkript + Unsicherheitszonen + demonstrative Treffer und entscheidet, ob get_video_frames_at mit den relevanten Zeitstempeln aufgerufen werden soll

Bei YouTube werden zuerst Untertitel versucht (sofort, bereits mit Zeitstempeln). Whisper ist der Fallback. Die gesamte Transkription erfolgt lokal — kein Audio wird an externe Dienste gesendet.

Cobalt-Einrichtung

Cobalt ist ein Open-Source-Medien-Downloader, der 21 Plattformen unterstützt. media-mcp verwendet es für Instagram. Du brauchst deine eigene Instanz — die öffentliche API erfordert JWT-Auth, die nicht Server-zu-Server funktioniert.

Docker (empfohlen)

# docker-compose.yml
services:
  cobalt:
    image: ghcr.io/imputnet/cobalt:11
    init: true
    read_only: true
    restart: unless-stopped
    ports:
      - 9000:9000/tcp
    environment:
      API_URL: "http://localhost:9000/"
    labels:
      - com.centurylinklabs.watchtower.scope=cobalt

  watchtower:
    image: ghcr.io/containrrr/watchtower
    restart: unless-stopped
    command: --cleanup --scope cobalt --interval 900 --include-restarting
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

docker compose up -d
curl http://localhost:9000/   # verify

API-Key-Auth hinzufügen

node -e "console.log(crypto.randomUUID())"   # generate key

Erstelle keys.json:

{
  "your-uuid": {
    "name": "media-mcp",
    "limit": "unlimited",
    "allowedServices": "all"
  }
}

Zur Cobalt-Umgebung hinzufügen:

environment:
  API_KEY_URL: "file:///keys.json"
  API_AUTH_REQUIRED: 1
volumes:
  - ./keys.json:/keys.json:ro

Cookies hinzufügen (für private Inhalte)

Erstelle cookies.json mit deiner Instagram-sessionid, mounte es als /cookies.json und setze COOKIE_PATH: "/cookies.json" in der Umgebung.

Produktions-Härtung

environment:
  CORS_WILDCARD: 0
  CORS_URL: "http://localhost"
  RATELIMIT_WINDOW: 60
  RATELIMIT_MAX: 100
  DURATION_LIMIT: 10800

Unterstützte Plattformen

Cobalt unterstützt 21 Plattformen. Aktuell verwendet media-mcp es für Instagram. Zukünftige Versionen werden weitere hinzufügen: YouTube, TikTok, Twitter/X, Reddit, Facebook, Pinterest, Snapchat, Bluesky, Twitch, Vimeo, SoundCloud, Dailymotion, Tumblr, Bilibili, Loom, Streamable, Rutube, Newgrounds, OK.ru, VK.

Ein-Befehl-Einrichtung

Kopiere den Inhalt von PROMPT.md und füge ihn in Claude Code ein. Er installiert alle Voraussetzungen, klont das Repository, konfiguriert alles und verbindet media-mcp automatisch.

Transkriptionssprache und -modell

Alle drei Transkriptions-Tools akzeptieren zwei optionale Parameter:

• language — ISO-639-1-Code (en, es, tr, de, ...) oder auto für automatische Erkennung. Standard ist Englisch. Bei YouTube werden Untertitel in dieser Sprache angefordert, bevor Whisper läuft.

• model — tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v3 oder large-v3-turbo. Bekannte Namen werden einmalig von HuggingFace nach ~/.media-mcp/models/ heruntergeladen und wiederverwendet. Ein absoluter Pfad zu einer beliebigen ggml-.bin-Datei funktioniert ebenfalls. Größere Modelle sind langsamer und genauer — large-v3-turbo ist der Sweet Spot, wenn base zu viel falsch versteht.

Entwicklung

npm run dev        # watch mode (recompiles on change)
npm run build      # one-time build
npm test           # run the unit test suite
npm run test:watch # tests in watch mode
npm start          # run the server

CI führt Build + Tests auf Node 20 und 22 für jeden Push und PR aus. Releases sind tag-ausgelöst: Das Pushen von v* veröffentlicht auf npm mit Provenienz, erstellt ein GitHub Release und pusht das Docker-Image zu GHCR.

Lizenz

MIT