media-mcp

Соцсети под рукой. 31 инструмент для Twitter/X, YouTube, Instagram и обработки видео — из Claude Desktop, Claude Code или любого MCP-клиента. 100% открытый исходный код.

Укажите твит — получите полный текст, метрики и транскрипцию видео. Дайте URL YouTube — получите транскрипт. Скиньте рилс из Instagram — получите скачанное медиа и транскрибированное аудио. Вся транскрипция выполняется локально через Whisper — аудио не покидает вашу машину.

Тезис: уши всегда, глаза — только когда уши подводят

Малые модели Whisper отлично слышат, но ужасно читают. Они неправильно расслышивают необычные имена. Они не могут транскрибировать текст на экране. Они пропускают вшитые субтитры. Для 90% вопросов о видео это неважно — сути достаточно.

Но когда пользователь спрашивает «какая команда установки в этом рилсе?» или «какой ник он показал?», одна лишь транскрипция уверенно даст неверный ответ. URL был на экране. Имя собственное было написано в подписи. Whisper ничего из этого не видел.

media-mcp транскрибирует с уверенностью по каждому токену через whisper-cli -ojf и помечает зоны неопределённости (где Whisper признаёт, что угадывал) и указательные фразы («заходите на наш», «эта команда», «в описании» — сильные сигналы того, что упоминается контент на экране). LLM читает эти маркеры и решает, вызывать ли get_video_frames_at для конкретных таймкодов, требующих визуальной проверки. Кадры извлекаются только тогда, когда это нужно. Чтением занимается собственное зрение LLM — без OCR, без второй модели.

Итог: у агента есть уши для каждого видео, глаза — только там, где уши подводят. Минимум кадров, максимум точности.

Related MCP server: youtube-mcp

Что он делает

• Получает твиты, ветки, профили, подписчиков, тренды и результаты поиска из Twitter/X (26 инструментов через REST API TwitterAPI.io, с опциональной поддержкой Xquik для пересекающихся read-инструментов)

• Транскрибирует аудио из видео локально с помощью whisper-cli — скачивает медиа, извлекает аудио через ffmpeg, запускает Whisper на вашем оборудовании, выдаёт уверенность по каждому токену и срабатывания указательных фраз, чтобы LLM знал, где аудиоканал ненадёжен

• Скачивает посты, рилсы и карусели Instagram в локальные папки через самостоятельно размещённый инстанс Cobalt

• Извлекает кадры из любого URL видео с настраиваемым FPS — или точно по массиву таймкодов через get_video_frames_at (с учётом кэша, без повторного скачивания при повторных запросах)

• Отслеживает пользователей Twitter в реальном времени и фильтрует твиты по правилам ключевых слов

• Кэширует скачанные видео в ~/.media-mcp/cache/videos/ (ключ — sha256 от URL, TTL 24 часа), чтобы транскрипция + поиск кадров по одному видео выполнялись за одно скачивание

Как это работает

LLM никогда не скрейпит HTML и не разбирает DOM. Каждый инструмент вызывает специально созданный API и возвращает структурированный, готовый для LLM текст.

Для текстовых данных (твиты, профили, тренды): один REST-запрос к TwitterAPI.io по умолчанию, разобранный в форматированный вывод. Установите TWITTER_BACKEND=xquik с XQUIK_API_KEY, чтобы использовать Xquik для пересекающихся read-инструментов.

Для транскрипции (видео в твитах, YouTube, рилсы Instagram): конвейер скачивает медиа в общий кэш, извлекает аудио через ffmpeg (16 кГц моно WAV), транскрибирует через whisper-cli с -ojf (output-json-full) для сохранения вероятностей по каждому токену, затем возвращает читаемый для LLM транскрипт с встроенными маркерами ⟨token p=0.XX⟩ плюс сводные блоки для зон неопределённости и указательных фраз. Для YouTube сначала пробуются субтитры (мгновенно) — Whisper используется только как запасной вариант.

Для визуальных данных (изображения Instagram, кадры видео): медиа скачивается в локальную папку, и возвращаются абсолютные пути к файлам, чтобы LLM мог читать их напрямую зрением. Извлечение кадров имеет два режима: массовый (extract_video_frames с настраиваемым FPS) и точечный (get_video_frames_at — один JPG на таймкод, для адресной проверки моментов, где транскрипция неуверенна).

Конвейер

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)

Транскрипция всегда включает уверенность по каждому токену и сканирование указательных фраз. LLM направляет запрос на извлечение кадров, когда эти сигналы говорят, что это нужно.

Вся транскрипция локальна. Все временные файлы удаляются. Скачанные видео хранятся в общем кэше (~/.media-mcp/cache/videos/) в течение 24 часов, чтобы повторные вызовы по тому же URL не скачивались заново. LLM получает структурированный текст или пути к файлам — никогда не сырой JSON из API.

Принципы проектирования

1. Структурированные данные, а не скрейпинг. Каждый инструмент вызывает специально созданный API. Никакого разбора HTML, никаких хрупких селекторов, никакой автоматизации браузера.

2. Только локальная транскрипция. Аудио никогда не покидает машину. Whisper работает на локальном оборудовании.

3. Сначала субтитры, потом Whisper. Не тратьте вычисления, когда платформа уже сделала работу.

4. Один инструмент — одна задача. Никаких многоцелевых инструментов с флагами режимов. Каждый инструмент делает ровно одну вещь.

5. Пути к файлам для визуального контента. Возвращайте абсолютные пути, чтобы LLM мог видеть изображения напрямую.

6. Уши всегда, глаза — только когда уши подводят. Транскрипция дёшева; токены зрения дороги. LLM видит кадры только на таймкодах, где Whisper признаёт неуверенность, или где говорящий явно ссылается на что-то на экране. Не на 1 fps. Не как ключевые кадры. Ровно там, где точность действительно нужна.

7. Никакого слоя OCR. Зрение Claude читает кадры напрямую. Одна модель, выполняющая все мультимодальные рассуждения, лучше двухмодельного шва, где OCR и зрение конкурируют.

Подробности полного конвейера, справочник инструментов и анти-паттерны — в SKILL.md.

Начало работы

npx (самый быстрый способ)

TWITTER_API_KEY=your_key npx media-mcp

Или зарегистрируйте его в Claude Code одной командой:

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

Базовая модель Whisper скачивается автоматически при первой транскрипции в ~/.media-mcp/models/. ffmpeg, whisper-cli и yt-dlp всё ещё нужно установить (см. Предварительные требования).

Docker

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

Образ включает ffmpeg, yt-dlp и whisper-cli. Модели и кэш видео сохраняются в томе /data.

Из исходников

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

Скачайте модель Whisper (необязательно — пропущенные модели загружаются по требованию):

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

Создайте .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)

Предварительные требования

Конфигурация

Claude Code

Добавьте в ~/.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

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows) — та же структура, что выше.

Переменные окружения

Инструменты

Twitter/X — 26 инструментов

TwitterAPI.io — бэкенд по умолчанию для всех инструментов Twitter/X. Установите TWITTER_BACKEND=xquik с XQUIK_API_KEY, чтобы отправлять пересекающиеся read-инструменты в Xquik вместо этого. Оба бэкенда возвращают одинаковый вывод инструментов, так что больше ничего не меняется.

Инструмент, доступный только через TwitterAPI.io, выдаёт понятную ошибку, если запустить TWITTER_BACKEND=xquik без TWITTER_API_KEY. Установите оба ключа, чтобы использовать все инструменты и при этом читать через Xquik.

Получение твитов

Получение профилей

Мониторинг в реальном времени

YouTube — 1 инструмент

Instagram — 1 инструмент

Cloudflare — 1 инструмент

Видео — 2 инструмента

Как работает транскрибация

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. Видео скачивается в ~/.media-mcp/cache/videos/<sha256>.mp4 (переиспользуется, если есть и моложе 24 часов)

2. ffmpeg извлекает аудио как моно WAV 16 кГц

3. whisper-cli транскрибирует локально с -ojf (output-json-full) — JSON включает значения p для каждого токена

4. Токены ниже p=0.5 объединяются в непрерывные отрезки (разрыв ≤150 мс) и помечаются как зоны неопределённости

5. Текст сегмента сканируется на указательные фразы, которые обычно ссылаются на содержимое экрана

6. LLM получает транскрипт по сегментам + зоны неопределённости + совпадения указательных фраз и решает, вызывать ли get_video_frames_at с соответствующими таймстампами

Для YouTube сначала пробуются субтитры (мгновенно, уже с таймстампами). Whisper — запасной вариант. Вся транскрибация происходит локально — аудио не отправляется во внешние сервисы.

Настройка Cobalt

Cobalt — это медиа-загрузчик с открытым исходным кодом, поддерживающий 21 платформу. media-mcp использует его для Instagram. Вам нужен собственный экземпляр — публичный API требует JWT-аутентификацию, которая не работает между серверами.

Docker (рекомендуется)

# 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-ключу

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

Создайте keys.json:

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

Добавьте в окружение cobalt:

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

Добавление cookies (для приватного контента)

Создайте cookies.json с вашим sessionid от Instagram, смонтируйте как /cookies.json и задайте COOKIE_PATH: "/cookies.json" в окружении.

Усиление безопасности для продакшена

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

Поддерживаемые платформы

Cobalt поддерживает 21 платформу. Сейчас media-mcp использует его для Instagram. В будущих версиях будут добавлены: YouTube, TikTok, Twitter/X, Reddit, Facebook, Pinterest, Snapchat, Bluesky, Twitch, Vimeo, SoundCloud, Dailymotion, Tumblr, Bilibili, Loom, Streamable, Rutube, Newgrounds, OK.ru, VK.

Настройка одной командой

Скопируйте содержимое PROMPT.md и вставьте его в Claude Code. Он установит все необходимые компоненты, клонирует репозиторий, настроит всё и подключит media-mcp автоматически.

Язык и модель транскрибации

Все три инструмента транскрибации принимают два необязательных параметра:

• language — код ISO 639-1 (en, es, tr, de, ...) или auto для автоматического определения. По умолчанию — английский. На YouTube субтитры запрашиваются на этом языке до запуска Whisper.

• model — tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v3 или large-v3-turbo. Известные названия один раз скачиваются с HuggingFace в ~/.media-mcp/models/ и переиспользуются. Абсолютный путь к любому ggml .bin файлу тоже работает. Модели большего размера медленнее и точнее — large-v3-turbo — оптимальный вариант, когда base слишком часто ошибается.

Разработка

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 запускает сборку и тесты на Node 20 и 22 для каждого пуша и PR. Релизы запускаются по тегам: пуш v* публикует в npm с provenance, создаёт GitHub Release и пушит Docker-образ в GHCR.

Лицензия

MIT