vidlens-mcp

AI はウェブを読めます。
今度は動画も見られます。

npx vidlens-mcp setup

• 動画をリサーチ： YouTube や公開ソーシャル動画を検索、文字起こし、比較し、出典を引用します。
• ローカルライブラリを構築： 一度インポートすれば、同じ動画を再取得せずに、文字起こし、コメント、フレーム、OCR を検索できます。
• 視覚的な証拠を確認： ビジュアルギャラリーと構造化されたクライアント出力で、該当するフレーム、タイムスタンプ、一致した理由、出典を確認できます。

VidLens は、AI エージェントに動画を見る力を与える MCP サーバーです。YouTube、X、TikTok、Instagram、その他の動画ページ、またはディスク上のファイルに対応します。リンクを貼り付けて質問すると、VidLens が文字起こしを読み、フレームを確認し、検証できるタイムスタンプ付きで回答します。取り込んだデータはすべてお使いのマシン上のライブラリに保存されるため、エージェントが同じ動画を二度見る必要はありません。

開始時に API キーは不要です。Claude Desktop、Claude Code、Codex で動作します。対応クライアントでは、VidLens の構造化された結果を、クライアント独自の応答画面上でネイティブなグラフ、カード、表、ビジュアルレポートに変換できます。

VidLens の動作を見る

▶ YouTube で 1:46 のデモを見る

---

試してみる

VidLens のセットアップが完了したら、以下のいずれかを AI クライアントに貼り付けます。

「YouTube で M5 Max MacBook Pro のレビューを検索してください。レビュアーの意見が一致している点と、食い違っている点は何ですか？」

VidLens は検索を行い、複数のレビュアーの文字起こしを読み、出典とタイムスタンプを添えて、共通見解と相違点をまとめます。

「この動画を文字起こしして要約してください：https://x.com/username/status/123...」

X、Instagram、TikTok の公開動画 URL を 1 つ指定するだけなら、通常 API キーは必要ありません。VidLens は動画を取得して文字起こしし、その文字起こしを保存するため、今回のセッションでも、今後のセッションでも、続けて質問できます。

「この動画でベンチマークのグラフを見せているフレームを見つけてください。」

ビジュアル検索では、画面上に表示されているスライド、グラフ、ホワイトボード、製品画像などを確認し、テキストによる推測だけでなく、タイムスタンプ付きの実際のフレーム画像をローカルブラウザーのギャラリーに表示します。

ネイティブクライアントでの表示

VidLens は、ソース、タイムスタンプ、スコア、OCR、説明、出所、制約など、持ち運び可能な構造化エビデンスを返します。Codex、Claude をはじめとする高機能なクライアントは、そのエビデンスをもとに、ネイティブのグラフ、比較カード、表、ビジュアルレポートを作成できます。

表示は埋め込み型の VidLens UI ではなく、クライアント側で行われます。抽出したフレームを確認する場合、searchVisualContent からブラウザーのギャラリーを開くこともできます。

---

仕組み

左側から動画ソースを入力します。VidLens は、YouTube API（キーが設定されている場合）、yt-dlp、直接ページ抽出のうち、利用可能な方法で動画を取り込み、トランスクリプト、フレーム、埋め込みをローカルライブラリに保存します。エージェントは、任意の MCP クライアントからそのライブラリを検索します。

信頼性を保つため、次の 2 つの保証が組み込まれています。

• 失敗ではなくフォールバック。 YouTube データツールは、利用を諦める前に複数の方法を試します。そのため、キーがない場合や割り当て上限に達した場合も、機能が壊れるのではなく、段階的に機能が制限されます。
• レスポンスに出所を明記。 ツールのレスポンスには、データの取得に使われた方法と、データに欠落があるかどうかが示されます。気づかないうちに機能が制限されることはありません。

すべてのデータは、ディスク上の 1 つのディレクトリに保存されます。外部データベースも Docker も必要ありません。ディレクトリをコピーすればバックアップでき、削除すれば初期状態に戻せます。

---

インストール

セットアップウィザード（推奨）

npx vidlens-mcp setup

ウィザードは Claude Desktop、Claude Code、Codex を検出し、VidLens に必要なローカル依存関係を確認したうえで、次のいずれかを選べます。

• 無料セットアップ（推奨）： API キーは不要です。YouTube の検索、トランスクリプト、メタデータ、ローカルライブラリをすぐに利用できます。
• 拡張セットアップ： オプションの API、音声認識、ウェブ検索、ブラウザー Cookie を個別に追加できます。不要な項目は Enter キーでスキップできます。保存済みの値は保持され、表示されることもありません。

Enter キーを押すと無料プランを選択できます。拡張機能が必要な場合は、いつでも npx vidlens-mcp setup --enhanced を実行してください。Claude Code の場合、セットアップでは VidLens をユーザー MCP レジストリにも登録し、共有 VidLens ワークフロースキルをインストールします。また、可能な場合は claude mcp list で登録結果を確認します。

手動での設定

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "vidlens-mcp": {
      "command": "npx",
      "args": ["-y", "vidlens-mcp", "serve"]
    }
  }
}

Claude Code — ウィザードの利用を推奨します。

npx vidlens-mcp setup --client claude_code
claude mcp list

手動で設定する場合は、同じ mcpServers.vidlens-mcp エントリを ~/.claude.json に追加します。

Codex — MCP サーバーと同梱の VidLens スキルをまとめて登録するため、セットアップヘルパーを使用してください。

npx vidlens-mcp setup --client codex

クライアントを再起動する

Claude Desktop を完全に終了してから再起動します（ウィンドウを閉じるだけではなく、⌘Q を押してください）。MCP サーバーは起動時に読み込まれます。Claude Code の場合は、新しいセッションを開始するか、セットアップ後に /mcp を実行してください。

ローカルチェックアウトからの実行

チェックアウト内で npm install を実行しても、バイナリは PATH に追加されません。チェックアウトから npm run setup を実行するか、開発中に vidlens-mcp コマンドを直接使う場合は npm install -g . または npm link を実行してください。

---

ライブラリ

VidLensは、セッションごとの一時的なメモ帳ではなく、動画作業のための永続的なメモリーです。インポートしたものはすべてVIDLENS_DATA_DIRの下にディスク上で保持されます。文字起こしコレクション、コメントコレクション、ダウンロードしたメディア、ビジュアルインデックスが含まれます。アクティブなコレクションも記憶されます。

1回の呼び出しで再利用できます。 セッションの開始時にrecallWorkspaceを呼び出すと、すでに保存されているすべての情報を簡潔にまとめた内容が返されるため、エージェントは再検索や再インポートの前に、何が保存されているかを把握できます。ツールの説明にも同じ注意が含まれているため、どのクライアントでもエージェントは再取得する前にまず確認します。

URLまたはアセットキーで再利用できます。 インポート済みのソーシャル動画の文字起こしは、元のURLまたはアセットキーを使って再度表示できます。再ダウンロードや再文字起こしは不要です。

エージェント間でライブラリを共有できます。 すべてのクライアントで同じデフォルトのデータディレクトリが使用されるため、Claude Desktop、Claude Code、Codexはすべて1つのライブラリを共有します。一方で動画をインポートし、もう一方で検索できます。

⚠️ VIDLENS_DATA_DIRをDropbox、iCloud、Google Drive、またはファイル同期フォルダーの中に置かないでください。 VidLensはSQLite（WAL使用）を使用しており、ファイル同期ツール配下の稼働中のデータベースは破損したり、競合コピーが作成されたりする可能性があります。データディレクトリはローカルディスクに置いてください。デフォルトの場所はその条件を満たしています。

---

YouTube以外にも対応

X、Instagram、TikTok、および一般的な動画ページでは、VidLensは機能の段階的な利用方式を採用しています。動作する中で最も低コストな方法を選び、APIキーは必須条件ではなく、機能を強化する手段として扱います。

方法	費用	最適な用途	動作
ローカルでの再利用	無料	以前にインポートしたもの全般	recallWorkspaceが保存済みの文字起こしまたはメディアを見つけるため、再取得は行われません
公開された直接URL	無料	1件のX投稿、Instagramリール／投稿、またはTikTok動画	yt-dlpが正規の投稿URLに匿名でアクセスします。字幕がないメディアはffmpegとローカルまたは設定済みのSTTで処理します
ブラウザー支援	対応ホストを利用できる場合は無料	投稿の検索や確認、または既存のサインイン済みセッションの利用	クライアントのブラウザー制御機能で正規URLと表示中のメタデータを取得し、URLをVidLensに渡します
ローカルファイルの受け渡し	無料	保存が許可されている動画	保存したファイルをインポートして、文字起こしとビジュアルインデックス作成を行います
APIによる強化	プロバイダーの料金体系による	大量処理、無人処理、または繰り返しの検出	設定済みのScrapeCreators、Brave、SerpAPI、YouTube、Gemini、またはOpenAIの機能が自動的に選択されます

注意点を3つ、明確に示します。

• ブラウザー支援はホストに依存します。 MCP サーバー自体はブラウザーを制御しません。クライアントが提供するブラウザーツールに依存し、利用できる機能はホストごとに異なります。
• 動画を視聴できても、エクスポートできるとは限りません。 ブラウザーで再生できる投稿でも、メディアが自動的にエクスポートされるとは限りません。
• 具体的なURLのみが対象です。 VidLensがインポートするのは特定の投稿または動画のURLのみで、プロフィール、探索ページ、ハッシュタグページ、人気ページは対象外です。

ダウンロード以外のソーシャル動画やローカル動画の作業を行う場合は、ffmpegをインストールしてください（macOSではbrew install ffmpeg）。フレーム抽出、ビジュアルインデックス作成、STTの音声分割にはffmpegが必要です。

---

ツール — 11モジュールにわたる47種類

探索 — YouTubeの検索と調査（1）

ツール	機能
exploreYouTube	複数クエリのランキング、文字起こしの要約、構造化されたベンチマークデータ、バックグラウンドでのインデックス作成に対応した、意図を考慮する検索です。個別のツール呼び出し5～8回分を1回にまとめます。

コア — 動画とチャンネルのインテリジェンス（7）

ツール	機能
findVideos	メタデータ付きで、クエリに基づいて YouTube を検索します
inspectVideo	タグ、エンゲージメント、言語、カテゴリなどの詳細なメタデータを確認します
inspectChannel	チャンネルの統計情報、説明、最近のアップロードを確認します
listChannelCatalog	チャンネルの全動画ライブラリを閲覧します
readTranscript	タイムスタンプとチャプター付きの全トランスクリプトを取得します
readComments	いいね数とエンゲージメント付きの上位コメントを取得します
expandPlaylist	任意のプレイリストに含まれるすべての動画を一覧表示します

ナレッジベース — トランスクリプトのセマンティック検索（7）

ツール	機能
importPlaylist	プレイリスト全体のトランスクリプトをインデックス化します
importVideos	URL または ID を指定して特定の動画をインデックス化します
searchTranscripts	インデックス化されたコンテンツを自然言語で検索します
listCollections	インデックス化されたコレクションを閲覧します
setActiveCollection	検索対象を1つのコレクションに限定します
clearActiveCollection	すべてのコレクションを対象に検索します
removeCollection	コレクションとそのインデックスを削除します

センチメントと分析（4）

ツール	機能
measureAudienceSentiment	コメントのセンチメントをテーマやリスクシグナルとともに分析します
analyzeVideoSet	複数の動画のパフォーマンスを比較します
analyzePlaylist	プレイリスト単位のエンゲージメント分析を行います
buildVideoDossier	1本の動画を包括的かつ詳細に分析します

クリエイターインテリジェンス（4）

ツール	機能
scoreHookPatterns	動画の冒頭が効果を発揮する要因を分析します
researchTagsAndTitles	タグとタイトルの最適化に関する分析情報を提供します
compareShortsVsLong	ショート動画と長尺動画のパフォーマンスを比較します
recommendUploadWindows	エンゲージメントを高める投稿時間を提案します

発見とトレンド（2）

ツール	機能
discoverNicheTrends	あらゆるトピックの勢い、飽和度、コンテンツの不足領域を調査します
exploreNicheCompetitors	チャンネルの状況と上位のパフォーマンスを調査します

あらゆる動画ソース（5）

ツール	機能
inspectVideoSource	YouTube、X、Instagram、TikTok、汎用 URL、ローカルファイルを解析し、ソースメタデータと機能フラグを取得します
searchVideoSources	YouTube とローカルアセットをネイティブ検索します。TikTok／Instagram の ScrapeCreators 対応に加え、設定可能な Brave／SerpAPI／DuckDuckGo のフォールバックも利用できます
searchSocialTrends	ScrapeCreators を通じてソーシャルプラットフォームを検索し、エンゲージメント指標と、利用可能な場合はインポート可能な URL を含むランキングを返します
importVideoSources	URL またはローカルファイルをローカルメディアストアにインポートします。必要に応じて、ビジュアルインデックスやトランスクリプトも作成できます
transcribeVideoSource	ネイティブ字幕または設定済みの STT を使用して、YouTube、ソーシャル／汎用 URL、ローカルファイルを文字起こしします

メディアアセット（5）

ツール	機能
downloadAsset	対応する任意のソースから動画、音声、サムネイルをダウンロードまたは取り込みます
listMediaAssets	保存済みのメディアファイルを閲覧します
removeMediaAsset	ダウンロード済みアセットを整理します
extractKeyframes	動画からキーフレームを抽出します
mediaStoreHealth	ストレージの使用状況と診断情報を確認します

ビジュアル検索とエビデンス（3）

ツール	機能
indexVisualContent	フレームを抽出し、Apple Vision の OCR と特徴プリント、Gemini によるフレームの説明、Gemini のセマンティック埋め込みを実行します
searchVisualContent	意味やテキストでフレームを検索します。タイムスタンプ付きのエビデンスを返し、外部ブラウザーのギャラリーを開くこともできます
findSimilarFrames	Apple Vision の特徴プリントを使用して、画像間のフレーム類似度を検索します

ビジュアル検索には、トランスクリプトとは別の専用インデックスを使用します。一致した各項目には、タイムスタンプ、ソース動画、OCR テキスト、ビジュアルの説明が含まれます。ローカルのフレームパスと file: URL は MCP の結果から除外されます。ブラウザーのギャラリーは、これらのパスをクライアントに公開することなく、画像をローカルで読み込みます。

コメントナレッジベース（6）

ツール	機能
importComments	動画のコメントを検索用にインデックス化します
searchComments	コメントコーパスを自然言語で検索します
listCommentCollections	コメントコレクションを一覧表示します
setActiveCommentCollection	コメント検索の対象を絞り込みます
clearActiveCommentCollection	すべてのコメントコレクションを検索します
removeCommentCollection	コメントコレクションを削除します

診断（3）

ツール	機能
recallWorkspace	すでにインポート済みのすべての内容をセッション開始時に要約します。再インポートを避けるため、最初に呼び出してください
checkSystemHealth	システム全体の診断レポートを表示します
checkImportReadiness	コンテンツのインポート前に検証します

---

オプションの API キー

VidLens はキーなしで動作します。規模の拡大と信頼性向上のため、キーを追加してください。

キー	利用できる機能	無料？	入手先
YOUTUBE_API_KEY	より詳細なメタデータ、コメント API、YouTube API 検索	Google の割り当て制限が適用されます	Google Cloud Console → YouTube Data API v3 を有効化 → API キーを作成
GEMINI_API_KEY	セマンティック検索やビジュアル検索向けの高品質な埋め込み、フレームの説明	プロバイダーの料金と制限が適用されます	Google AI Studio
OPENAI_API_KEY	文字起こし用のオプションの STT プロバイダー	有料	OpenAI Platform
SCRAPECREATORS_API_KEY	TikTok、Instagram、Threads、Pinterest、Reddit、および対応エンドポイントのソーシャル検索とトレンド情報を直接取得	プロバイダーの料金が適用されます	ScrapeCreators
BRAVE_API_KEY / SERPAPI_KEY	ソーシャルおよび一般的な URL の検出に使う構造化ウェブ検索	異なります	Brave Search API または SerpAPI

⚠️ YouTube と Gemini のキーは、別々の Google サービス用の別個のキーです。 Gemini のキーは YouTube API の呼び出しには使えません。その逆も同様です。

# Free setup asks for no keys.
npx vidlens-mcp setup

# Enhanced setup optionally prompts for keys, STT, web search, and cookies.
npx vidlens-mcp setup --enhanced

# Or pass everything non-interactively.
npx vidlens-mcp setup \
  --youtube-api-key YOUR_YOUTUBE_KEY \
  --gemini-api-key YOUR_GEMINI_KEY \
  --stt-provider auto \
  --cookies-from-browser chrome

Cookie と音声テキスト変換

匿名アクセスにレート制限を設けているプラットフォームでは、ウィザードを使ってブラウザープロファイルまたはファイルパスごとに Cookie を保存できます。

npx vidlens-mcp setup --cookies-from-browser chrome --cookies-profile Default
npx vidlens-mcp setup --x-cookies-file /path/to/x-cookies.txt

または、環境変数で指定します：VIDLENS_COOKIES_FROM_BROWSER、VIDLENS_X_COOKIES_FILE、VIDLENS_INSTAGRAM_COOKIES_FILE、VIDLENS_TIKTOK_COOKIES_FILE。

STT は自動的に選択されます。まずローカルの whisper.cpp、次に Gemini、最後に OpenAI を使用します。VIDLENS_STT_PROVIDER=whisper-cpp|gemini|openai|none|auto で上書きできます。ウィザードで尋ねられたときは、ほとんどの場合、Enter キーを押して auto を選ぶのが適切です。

---

CLI

npx vidlens-mcp               # Start MCP server (stdio)
npx vidlens-mcp serve         # Start MCP server (explicit)
npx vidlens-mcp setup         # Configure clients, keys, STT, cookies
npx vidlens-mcp doctor        # Run diagnostics
npx vidlens-mcp doctor --no-live   # Diagnostics without network checks
npx vidlens-mcp update-deps   # Refresh managed yt-dlp and Deno helpers
npx vidlens-mcp version       # Print version

doctor は、Node.js のバージョン、yt-dlp の最新状態、STT およびウェブ検索プロバイダー、API キーの有効性、データディレクトリの健全性、Claude Desktop、Claude Code、Codex の MCP クライアント登録状況を確認します。

---

要件

要件	状態	備考
Node.js ≥ 22	必須	node:sqlite を使用します。node --version で確認してください
yt-dlp	自動インストール	npx vidlens-mcp setup の実行中にダウンロードされます
ffmpeg + ffprobe	推奨	メディアの検証、フレーム抽出、ビジュアルインデックス作成、STT 音声処理に必要です
YouTube API キー	オプション	より詳細なメタデータとコメントへのアクセス
Gemini API キー	オプション	より優れた埋め込みとフレームの説明
macOS	オプション	Apple Vision によってネイティブ OCR と画像類似性検索を利用できます。他のプラットフォームでは、設定により Gemini の説明を利用できます

---

セキュリティとプライバシー

• ライブラリ（トランスクリプト、フレーム、埋め込み、メディア）はローカルに保存され、お使いのマシンから外部に出ることはありません。ネットワーク呼び出しは、クエリ対象のソースと設定した API にのみ行われます。
• セットアップでは、設定したキーをローカルの MCP クライアント設定に保存します。キー入力がマスクされる、対話型の拡張セットアップをおすすめします。CLI フラグで指定したキーは、シェルの履歴に残る可能性があります。エラーメッセージはシークレットリダクターを通るため、キーや Cookie のパスがツールの出力に表示されることはありません。
• チャンネルページと一般的な URL の取得では、プライベート、リンクローカル、ループバックの各アドレスを拒否します（SSRF ガード）。意図的にローカルで使用する場合の回避策：VIDLENS_ALLOW_PRIVATE_URLS=1。

---

トラブルシューティング

Claude Desktop で「Tool not found」と表示される。 完全に終了（⌘Q）してから、再度開いてください。MCP サーバーは起動時にのみ読み込まれます。

「YOUTUBE_API_KEY not configured」という警告が表示される。 情報を示すもので、エラーではありません。VidLens はこのキーがなくても動作します。

「API_KEY_SERVICE_BLOCKED」と表示される。 このキーでは、要求された Google サービスを呼び出すことが許可されていません。Google Cloud Console で YouTube Data API v3 を有効にし、キーの API 制限でその API を許可してください。VidLens の実行環境に適したアプリケーション制限を設定してください。短時間の診断のみを目的とし、直後に再び制限する場合を除き、キーの制限を解除しないでください。

Gemini のキーで YouTube を利用できない。 これらは別々のサービスであり、キーも異なります。任意の API キーを参照してください。

ソーシャル動画をダウンロードできるが、ビジュアル分析に失敗する。 ffmpeg をインストールしてから、セットアップを再実行してください。

brew install ffmpeg

npx vidlens-mcp doctor --no-live

downloadAsset は ffmpeg がなくても動画を取得できることがよくありますが、indexVisualContent、extractKeyframes、メディアの検証、STT による音声処理には ffmpeg または ffprobe が必要です。

その他の問題：

npx vidlens-mcp doctor

---

ライセンス

MIT

GitHub · npm · Model Context Protocol

1.5.3 エージェント契約の変更

listChannelCatalog は、上限付きの scanLimit と、新たな候補を検出するための refresh: true を受け付けます。maxResults は返される一致数を制限するものであり、最初のアップロード取得範囲を制限するものではありません。返された網羅状況と形式の根拠を確認してください。動画の長さだけでは、その短い動画が YouTube ショートであるとは証明できません。また、形式を特定できない動画は、ショートまたは長尺動画のみを求めるリクエストから除外されます。

readTranscript は、秒数や行数ではなく、ゼロ始まりの UTF-16 テキストオフセットを使用します。トランスクリプト全体を取得するには、mode: "full", offset: 0, limit: 15000 から始め、longVideoHandling.pagination.nextOffset をたどって hasMore が false になるまで続けてください。Unicode のサロゲートペアが分割されないよう、ページの長さが 1 コード単位短くなる場合があります。呼び出し元がペアの途中から開始した場合は、有効なオフセットが返されます。上限は 1,000 から 64,000 までの整数です。オフセットまたは上限を明示的に指定しない場合、32,000 コード単位を超える全トランスクリプトには、開示されているキーモーメントへのフォールバックが適用されます。

ネイティブ MCP 呼び出しでは、予期しない引数名や無効な整数ページネーションを、誤記を黙って無視するのではなく拒否するようになりました。searchVisualContent と findSimilarFrames は、デフォルトでブラウザーを開かずに構造化された結果を返します。ギャラリーを作成して開くには、openGallery: true を明示的に指定してください。クライアントの承認ポリシーは引き続き適用されます。

任意の型付きフィールドは null として送信せず、省略してください。dryRun は、そのツールのスキーマに記載されている場合のみ渡してください。分類ベースの分析には、形式不明の動画も含まれるようになりました。動画の長さのみを使った傾向結果では、ショート動画への該当を判断できません。また、プロバイダーから日付やエンゲージメントデータが提供されない場合、比較結果が一部のみになることがあります。比較対象のグループがない場合に、架空のパーセンテージによる推奨が示されることはなくなりました。