media-mcp

ソーシャルメディアを指先で。Twitter/X、YouTube、Instagram、動画処理にわたる31のツールを、Claude Desktop、Claude Code、または任意のMCPクライアントから利用できます。100%オープンソース。

ツイートを指定すれば、全文、メトリクス、動画の文字起こしを取得できます。YouTubeのURLを渡せば文字起こしを取得。Instagramのリールをドロップすれば、メディアのダウンロードと音声の文字起こしを実行。すべての文字起こしはWhisperでローカル実行されるため、音声がマシンの外に出ることはありません。

基本方針: 耳は常に、目は耳が役に立たないときだけ

小型のWhisperモデルは「聞く」のは得意ですが「読む」のは苦手です。珍しい名前を聞き間違えます。画面上のテキストを文字起こしできません。焼き込み字幕をスキップします。動画に関する質問の90%ではこれは問題になりません——概要がわかれば十分だからです。

しかし、ユーザーが*「このリールのインストールコマンドは?」や「彼が見せたハンドル名は?」*と尋ねた場合、文字起こしだけでは自信満々に間違った答えを返します。URLは画面に表示されていました。固有名詞は字幕に綴られていました。Whisperはそのどれも見ていません。

media-mcpはwhisper-cli -ojfでトークンごとの信頼度付きで文字起こしを行い、不確実ゾーン(Whisperが推測していたことを認める箇所)と指示表現("visit our"、"this command"、"in the bio"——画面上のコンテンツが参照されている強いシグナル)にフラグを立てます。LLMはそれらのマーカーを読み、視覚的な検証が必要な特定のタイムスタンプに対してget_video_frames_atを呼び出すかどうかを判断します。フレームは必要なときだけ取り出されます。読み取りはLLM自身の視覚が行います——OCRも追加モデルも不要です。

結果: エージェントはすべての動画に耳を持ち、耳が役に立たない場所にだけ目を持ちます。最小限のフレーム、最大限の精度。

Related MCP server: youtube-mcp

機能

• 取得: Twitter/Xからツイート、スレッド、プロフィール、フォロワー、トレンド、検索結果を取得(26ツール、TwitterAPI.io REST API経由。重複する読み取りツールにはオプションでXquik対応)

• 文字起こし: whisper-cliで動画音声をローカル文字起こし——メディアをダウンロードし、ffmpegで音声を抽出し、お使いのハードウェアでWhisperを実行し、トークンごとの信頼度と指示表現のヒットを出力して、LLMが音声チャネルが信頼できない箇所を把握できるようにします

• ダウンロード: セルフホストのCobaltインスタンス経由でInstagramの投稿、リール、カルーセルをローカルフォルダにダウンロード

• フレーム抽出: 任意の動画URLから設定可能なFPSでフレームを抽出——またはget_video_frames_atでタイムスタンプの配列を指定して正確に抽出(キャッシュ対応、フォローアップ時の再ダウンロードなし)

• 監視: Twitterユーザーをリアルタイムで監視し、キーワードルールでツイートをフィルタリング

• キャッシュ: ダウンロードした動画を~/.media-mcp/cache/videos/にキャッシュ(URLのsha256をキーに、24時間TTL)し、同じ動画の文字起こし+フレーム検索を1回のダウンロードで完了

仕組み

LLMはHTMLをスクレイピングしたりDOMを解析したりしません。すべてのツールが専用のAPIを呼び出し、構造化されたLLM対応テキストを返します。

テキストデータ(ツイート、プロフィール、トレンド): デフォルトではTwitterAPI.ioへのREST呼び出し1回で、整形された出力にパースされます。TWITTER_BACKEND=xquikとXQUIK_API_KEYを設定すると、重複する読み取りツールにXquikを使用します。

文字起こし(ツイート動画、YouTube、Instagramリール): パイプラインはメディアを共有キャッシュにダウンロードし、ffmpegで音声を抽出し(16kHzモノラルWAV)、トークンごとの確率を保持するために-ojf(output-json-full)を指定してwhisper-cliで文字起こしし、インラインの⟨token p=0.XX⟩マーカーと不確実ゾーン・指示表現のサマリーブロックを含むLLM可読な文字起こしを返します。YouTubeではまず字幕を試します(即時)——Whisperはフォールバックのみです。

視覚データ(Instagram画像、動画フレーム): メディアはローカルフォルダにダウンロードされ、絶対ファイルパスが返されるため、LLMは視覚で直接読み取れます。フレーム抽出には2つのモードがあります: 一括(extract_video_frames、設定可能なFPS)と精密(get_video_frames_at——タイムスタンプごとに1枚の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が受け取るのは構造化テキストまたはファイルパス——生のAPI JSONではありません。

設計原則

1. スクレイピングではなく構造化データ。 すべてのツールが専用のAPIを呼び出します。HTML解析も、壊れやすいセレクタも、ブラウザ自動化もありません。

2. ローカル文字起こしのみ。 音声がマシンの外に出ることはありません。Whisperはローカルハードウェアで実行されます。

3. 字幕優先、Whisperは次。 プラットフォームがすでに作業を済ませている場合に計算リソースを消費しません。

4. 1ツール1ジョブ。 モードフラグ付きの多目的ツールはありません。各ツールは正確に1つのことだけを行います。

5. 視覚コンテンツにはファイルパス。 絶対パスを返し、LLMが画像を直接見られるようにします。

6. 耳は常に、目は耳が役に立たないときだけ。 文字起こしは安価で、視覚トークンは高価です。LLMがフレームを見るのは、Whisperが不確かだと認めたタイムスタンプ、または話者が画面上の何かを明示的に参照している箇所だけです。毎秒1フレームでも、キーフレームでもありません。精度が実際に必要とする場所にだけです。

7. OCRレイヤーなし。 Claudeの視覚がフレームを直接読み取ります。1つのモデルがすべてのマルチモーダル推論を行う方が、OCRと視覚が競合する2モデルの継ぎ目より優れています。

完全なパイプラインの詳細、ツールリファレンス、アンチパターンについてはSKILL.mdを参照してください。

はじめに

npx(最速)

TWITTER_API_KEY=your_key npx media-mcp

または、1コマンドでClaude Codeに登録:

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

Whisperのbaseモデルは、最初の文字起こし時に~/.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を設定すると、重複する読み取りツールがXquikに送信されます。両バックエンドとも同じツール出力を返すため、他に変更はありません。

TwitterAPI.io 専用ツールは、TWITTER_API_KEY を設定せずに TWITTER_BACKEND=xquik を実行すると明確なエラーを返します。両方のキーを設定すれば、すべてのツールを使いつつ 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 が音声を16kHzモノラルWAVとして抽出

3. whisper-cli が -ojf（output-json-full）でローカルに文字起こし — JSON にはトークンごとの p 値が含まれる

4. p=0.5 未満のトークンは連続するスパン（≤150msのギャップ）に統合され、不確実ゾーンとして報告される

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

クッキーの追加（非公開コンテンツ用）

Instagram の sessionid を含む cookies.json を作成し、/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 の自動接続が行われます。

文字起こしの言語とモデル

3つの文字起こしツールはすべて、2つのオプションパラメータを受け付けます:

• 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は、すべてのプッシュとPRに対してNode 20および22でビルドとテストを実行します。リリースはタグでトリガーされます。v*をプッシュすると、provenance付きでnpmに公開され、GitHub Releaseが作成され、DockerイメージがGHCRにプッシュされます。

ライセンス

MIT