media-mcp

Redes sociales al alcance de tu mano. 31 herramientas para Twitter/X, YouTube, Instagram y procesamiento de vídeo — desde Claude Desktop, Claude Code o cualquier cliente MCP. 100 % código abierto.

Apunta a un tuit y obtén el texto completo, las métricas y la transcripción del vídeo. Dale una URL de YouTube y obtén la transcripción. Suelta un reel de Instagram y descarga el contenido multimedia además de transcribir el audio. Toda la transcripción se ejecuta localmente mediante Whisper: el audio nunca sale de tu máquina.

La tesis: oídos siempre, ojos solo cuando los oídos fallan

Los modelos Whisper pequeños son excelentes para oír, pero pésimos para leer. Escuchan mal los nombres poco comunes. No pueden transcribir texto en pantalla. Se saltan los subtítulos incrustados. Para el 90 % de las preguntas sobre un vídeo esto no importa: la idea general es suficiente.

Pero cuando un usuario pregunta "¿cuál es el comando de instalación en este reel?" o "¿cuál es el usuario que mostró?", la transcripción por sí sola dará con seguridad una respuesta incorrecta. La URL estaba en pantalla. El nombre propio estaba escrito en el subtítulo. Whisper nunca vio nada de eso.

media-mcp transcribe con confianza por token mediante whisper-cli -ojf y marca zonas de incertidumbre (donde Whisper admite que estaba adivinando) y frases demostrativas ("visita nuestro", "este comando", "en la bio" — señales claras de que se está haciendo referencia a contenido en pantalla). El LLM lee esos marcadores y decide si debe llamar a get_video_frames_at en las marcas de tiempo específicas que necesitan verificación visual. Los fotogramas solo salen cuando es necesario. La propia visión del LLM hace la lectura: sin OCR, sin segundo modelo.

Resultado: el agente tiene oídos en cada vídeo, ojos solo donde los oídos fallan. Mínimos fotogramas, máxima precisión.

Related MCP server: youtube-mcp

Qué hace

• Obtiene tuits, hilos, perfiles, seguidores, tendencias y resultados de búsqueda de Twitter/X (26 herramientas mediante la API REST de TwitterAPI.io, con soporte opcional de Xquik para herramientas de lectura superpuestas)

• Transcribe audio de vídeo localmente con whisper-cli — descarga el contenido multimedia, extrae el audio con ffmpeg, ejecuta Whisper en tu hardware y emite confianza por token y coincidencias de frases demostrativas para que el LLM sepa dónde el canal de audio no es fiable

• Descarga publicaciones, reels y carruseles de Instagram a carpetas locales mediante una instancia de Cobalt autoalojada

• Extrae fotogramas de cualquier URL de vídeo a FPS configurables — o con precisión en un array de marcas de tiempo mediante get_video_frames_at (con caché, sin re-descargas en llamadas posteriores)

• Supervisa usuarios de Twitter en tiempo real y filtra tuits por reglas de palabras clave

• Almacena en caché los vídeos descargados en ~/.media-mcp/cache/videos/ (clave sha256-de-URL, TTL de 24 h) para que la transcripción + la búsqueda de fotogramas del mismo vídeo ocurran en una sola descarga

Cómo funciona

El LLM nunca hace scraping de HTML ni analiza el DOM. Cada herramienta llama a una API específica y devuelve texto estructurado y listo para el LLM.

Para datos de texto (tuits, perfiles, tendencias): una llamada REST a TwitterAPI.io por defecto, analizada en una salida formateada. Configura TWITTER_BACKEND=xquik con XQUIK_API_KEY para usar Xquik en las herramientas de lectura superpuestas.

Para transcripción (vídeos de tuits, YouTube, reels de Instagram): el pipeline descarga el contenido multimedia a la caché compartida, extrae el audio con ffmpeg (WAV mono de 16 kHz), transcribe con whisper-cli usando -ojf (output-json-full) para conservar las probabilidades por token, y luego devuelve una transcripción legible por el LLM con marcadores en línea ⟨token p=0.XX⟩ además de bloques de resumen para zonas de incertidumbre y frases demostrativas. Para YouTube, primero se intentan los subtítulos (instantáneos): Whisper es solo el respaldo.

Para datos visuales (imágenes de Instagram, fotogramas de vídeo): el contenido multimedia se descarga a una carpeta local y se devuelven rutas de archivo absolutas para que el LLM pueda leerlas directamente con visión. La extracción de fotogramas tiene dos modos: masivo (extract_video_frames a FPS configurables) y de precisión (get_video_frames_at — un JPG por marca de tiempo, para verificación específica de momentos inciertos en la transcripción).

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)

La transcripción siempre incluye confianza por token y análisis de frases demostrativas. El LLM se dirige a la extracción de fotogramas cuando esas señales indican que es necesario.

Toda la transcripción es local. Todos los archivos temporales se limpian. Los vídeos descargados viven en una caché compartida (~/.media-mcp/cache/videos/) durante 24 h para que las llamadas posteriores a la misma URL no se vuelvan a descargar. El LLM recibe texto estructurado o rutas de archivo, nunca JSON crudo de la API.

Principios de diseño

1. Datos estructurados, no scraping. Cada herramienta llama a una API específica. Sin análisis de HTML, sin selectores frágiles, sin automatización de navegador.

2. Solo transcripción local. El audio nunca sale de la máquina. Whisper se ejecuta en hardware local.

3. Subtítulos primero, Whisper segundo. No gastes cómputo cuando la plataforma ya hizo el trabajo.

4. Una herramienta, un trabajo. Sin herramientas multipropósito con banderas de modo. Cada herramienta hace exactamente una cosa.

5. Rutas de archivo para contenido visual. Devuelve rutas absolutas para que el LLM pueda ver las imágenes directamente.

6. Oídos siempre, ojos solo cuando los oídos fallan. La transcripción es barata; los tokens de visión son caros. El LLM ve fotogramas solo en las marcas de tiempo donde Whisper admite que no estaba seguro, o donde el hablante hace referencia explícita a algo en pantalla. No a 1 fps. No como fotogramas clave. Exactamente donde la precisión realmente lo necesita.

7. Sin capa de OCR. La visión de Claude lee los fotogramas directamente. Un solo modelo haciendo todo el razonamiento multimodal supera a un modelo de dos capas donde el OCR y la visión compiten.

Consulta SKILL.md para los detalles completos del pipeline, la referencia de herramientas y los anti-patrones.

Comenzar

npx (lo más rápido)

TWITTER_API_KEY=your_key npx media-mcp

O regístralo con Claude Code en un solo comando:

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

El modelo base de Whisper se descarga automáticamente en la primera transcripción en ~/.media-mcp/models/. ffmpeg, whisper-cli y yt-dlp aún deben instalarse (consulta Requisitos previos).

Docker

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

La imagen incluye ffmpeg, yt-dlp y whisper-cli. Los modelos y la caché de vídeos persisten en el volumen /data.

Desde el código fuente

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

Descarga el modelo de Whisper (opcional: los modelos omitidos se obtienen bajo demanda):

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

Crea .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)

Requisitos previos

Configuración

Claude Code

Añade a ~/.claude/settings.json:

{
  "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

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows) — misma estructura que arriba.

Variables de entorno

Herramientas

Twitter/X — 26 herramientas

TwitterAPI.io es el backend predeterminado para todas las herramientas de Twitter/X. Configura TWITTER_BACKEND=xquik con XQUIK_API_KEY para enviar las herramientas de lectura superpuestas a Xquik en su lugar. Ambos backends devuelven la misma salida de herramientas, así que nada más cambia.

Una herramienta exclusiva de TwitterAPI.io lanza un error claro cuando ejecutas TWITTER_BACKEND=xquik sin TWITTER_API_KEY. Configura ambas claves para usar todas las herramientas y seguir leyendo a través de Xquik.

Obtener tweets

Obtener perfiles

Monitorización en tiempo real

YouTube — 1 herramienta

Instagram — 1 herramienta

Cloudflare — 1 herramienta

Vídeo — 2 herramientas

Cómo funciona la transcripción

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. El vídeo se descarga en ~/.media-mcp/cache/videos/<sha256>.mp4 (se reutiliza si existe y tiene menos de 24 h)

2. ffmpeg extrae el audio como WAV mono de 16 kHz

3. whisper-cli transcribe localmente con -ojf (output-json-full): el JSON incluye valores p por token

4. Los tokens por debajo de p=0.5 se fusionan en tramos contiguos (hueco ≤150 ms) y se notifican como zonas de incertidumbre

5. El texto del segmento se analiza en busca de frases demostrativas que suelen referirse a contenido en pantalla

6. El LLM recibe la transcripción a nivel de segmento + zonas de incertidumbre + coincidencias demostrativas, y decide si llamar a get_video_frames_at con las marcas de tiempo relevantes

Para YouTube, primero se prueban los subtítulos (al instante, ya con marcas de tiempo). Whisper es el plan B. Toda la transcripción ocurre localmente: no se envía audio a servicios externos.

Configuración de Cobalt

Cobalt es un descargador de medios de código abierto compatible con 21 plataformas. media-mcp lo usa para Instagram. Necesitas tu propia instancia: la API pública requiere autenticación JWT que no funciona de servidor a servidor.

Docker (recomendado)

# 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

Añadir autenticación con clave API

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

Crea keys.json:

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

Añádelo al entorno de cobalt:

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

Añadir cookies (para contenido privado)

Crea cookies.json con tu sessionid de Instagram, móntalo como /cookies.json y establece COOKIE_PATH: "/cookies.json" en el entorno.

Endurecimiento para producción

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

Plataformas compatibles

Cobalt admite 21 plataformas. Actualmente media-mcp lo usa para Instagram. Las versiones futuras añadirán más: YouTube, TikTok, Twitter/X, Reddit, Facebook, Pinterest, Snapchat, Bluesky, Twitch, Vimeo, SoundCloud, Dailymotion, Tumblr, Bilibili, Loom, Streamable, Rutube, Newgrounds, OK.ru, VK.

Configuración en un solo comando

Copia el contenido de PROMPT.md y pégalo en Claude Code. Instalará todos los requisitos previos, clonará el repositorio, configurará todo y conectará media-mcp automáticamente.

Idioma y modelo de transcripción

Las tres herramientas de transcripción aceptan dos parámetros opcionales:

• language — código ISO 639-1 (en, es, tr, de, ...) o auto para autodetección. El valor predeterminado es inglés. En YouTube, los subtítulos se solicitan en este idioma antes de que se ejecute Whisper.

• model — tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v3 o large-v3-turbo. Los nombres conocidos se descargan una vez desde HuggingFace en ~/.media-mcp/models/ y se reutilizan. También funciona una ruta absoluta a cualquier archivo .bin de ggml. Los modelos más grandes son más lentos y más precisos: large-v3-turbo es el punto óptimo cuando base no entiende demasiado bien.

Desarrollo

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 ejecuta compilación + pruebas en Node 20 y 22 para cada push y PR. Los lanzamientos se activan por etiquetas: al hacer push de v* se publica en npm con procedencia, se crea una GitHub Release y se envía la imagen de Docker a GHCR.

Licencia

MIT