VidWords YouTube

VidWords YouTube MCP サーバー

AI エージェントが YouTube 動画を読み取り、回答の根拠となった正確な秒数を引用できる、ホスト型のModel Context Protocolサーバーです。

言語モデルは動画を視聴できません。このエンドポイントを指定すると、トランスクリプトの検索、保存済み動画の検索、動画のフレーム（スライド、グラフ、デモ、画面上のテキスト）の読み取り、そして表示前に検証される引用付きの質問回答に使える14個のツールを利用できるようになります。

連携コードは不要です。スクレイピングも不要です。プロキシプールも不要です。

https://vidwords.com/mcp

設定はこのURLだけです。クライアントはOAuthでサインインするため、探したり貼り付けたりするキーは不要です。ヘッドレスクライアントは代わりに Authorization: Basic <your-api-token> を送信できます。

リモート専用のホスト型サービスであり、インストールもセルフホストも不要です。このリポジトリは、そのエンドポイントの公開マニフェスト、設定リファレンス、課題管理用です。

---

クイックスタート

ほとんどのクライアントでは、トークンはまったく必要ありません。 このサーバーはOAuthに対応しているため、クライアントが自身を登録し、VidWordsへのサインイン画面を表示して、自動更新する認証情報を保存します。サインインの手順中にアカウントを作成できます。無料プランには月25件のCloud Requestsと200 AI Unitsが含まれているため、費用をかけずに設定して利用できます。

Claude（claude.aiおよびClaude Desktop）

1. Customize → Connectorsを開き、+ Add → Add custom connectorを選択します。
2. URL：https://vidwords.com/mcp
3. OAuthクライアントのオプションでRegister automaticallyを選択します。VidWordsが各コネクターを独自に登録するため（動的クライアント登録）、Claudeのデフォルトの「published identity」オプションでは接続できません。
4. 接続してVidWordsにサインインし、承認します。

TeamプランまたはEnterpriseプランでは、オーナーがOrganization settings → Connectors → Add → Custom → Webから先に追加します。その後、メンバーはCustomize → Connectorsから接続します。

ChatGPT

1. chatgpt.comで**Pluginsを開き、+**を選択してから、Add custom MCP serverを選択します。
2. 名前：VidWords · サーバーURL：https://vidwords.com/mcp · 認証：OAuth。
3. リスク警告を受け入れ、Create as a pluginを選択してから、VidWordsにサインインし、承認します。
4. 新しいプラグインをInstallし、チャットで@を入力してVidWordsを選択します。

この操作はウェブ上で行ってください。ワークスペースアカウントでは、管理者がカスタムMCPサーバーを許可する必要がある場合があります。

どちらの場合も、ホストが自身を登録し、VidWordsへのサインイン画面を表示します。さらに、要求されている内容が明記された同意画面が表示されます。登録しただけでは何も許可されません。アクセスは、サインインしたユーザーがApproveをクリックした場合にのみ開始されます。また、接続中のセッションはAPI & MCPページから即時に取り消せます。

設定ファイルを使った Claude Desktop の設定

claude_desktop_config.json で実行できるのは**ローカル（stdio）**サーバーのみです。リモートの url エントリはサポートされておらず、ファイルの mcpServers セクションが消去されたという報告もあります。それでもファイルでサーバーを宣言するには、mcp-remote を使ってブリッジします。ブラウザーで同じサインインフローが実行されるため、貼り付けるものはありません。

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vidwords.com/mcp"]
    }
  }
}

ファイルを編集した後、Claude Desktop を終了して再起動してください。

Claude Code

claude mcp add --transport http vidwords https://vidwords.com/mcp

その後、セッションで /mcp と入力し、Authenticate を選択してください。

Cursor — ワンクリック、または .cursor/mcp.json

上の Add to Cursor ボタンを使うか、次のように設定してください。

{
  "mcpServers": {
    "vidwords": {
      "url": "https://vidwords.com/mcp"
    }
  }
}

Cursor ではサーバーに Needs login と表示されます。そこを一度クリックすると、ブラウザーで OAuth フローが実行されます。このファイルにはシークレットが含まれないため、以下のヘッダー設定とは異なり、安全にコミットできます。

VS Code

上の Add to VS Code ボタンを使うか、.vscode/mcp.json に次の内容を設定してください。

{
  "servers": {
    "vidwords": { "type": "http", "url": "https://vidwords.com/mcp" }
  }
}

サーバーの初回起動時に、VS Code からサインインを求められます。

Codex CLI

codex mcp add vidwords --url https://vidwords.com/mcp
codex mcp login vidwords

静的トークンを使う場合

CI、コンテナー、または OAuth に対応していないクライアントでは、ヘッダーを使って認証します。vidwords.com/register でアカウントを作成し、メールアドレスを確認してから、 API & MCP ページ でキーを作成してください。キーの値が表示されるのは、作成時の一度だけです。

Claude Code

claude mcp add --transport http vidwords https://vidwords.com/mcp \
  --header "Authorization: Basic YOUR_API_TOKEN"

Claude Desktop — claude_desktop_config.json

上記と同じ mcp-remote ブリッジを使い、サインインの代わりにキーを指定します。キーは env に設定してください。Windows の Claude Desktop（および Cursor、Codex CLI）は args 内のスペースをエスケープしないため、Basic YOUR_API_TOKEN をそこに記述すると二つに分割されます。以下は mcp-remote の README に記載されている回避策です。

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vidwords.com/mcp",
               "--header", "Authorization:${VIDWORDS_MCP_AUTH}"],
      "env": { "VIDWORDS_MCP_AUTH": "Basic YOUR_API_TOKEN" }
    }
  }
}

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "vidwords": {
      "url": "https://vidwords.com/mcp",
      "headers": { "Authorization": "Basic YOUR_API_TOKEN" }
    }
  }
}

バージョン管理の対象から除外するか、代わりに ~/.cursor/mcp.json を使ってください。ヘッダーには有効な認証情報が含まれます。

Codex CLI — ~/.codex/config.toml

[mcp_servers.vidwords]
url = "https://vidwords.com/mcp"
env_http_headers = { "Authorization" = "VIDWORDS_MCP_AUTH" }

export VIDWORDS_MCP_AUTH="Basic YOUR_API_TOKEN"

bearer_token_env_var は使わないでください。一見適切そうなフィールドですが、Authorization: Bearer <value> を送信します。このサーバーの認証方式は Basic です。

カスタムヘッダーに対応していないクライアント、および Docker

このリポジトリには、小型のstdio プロキシ（src/index.js）も含まれています。stdin/stdout で MCP 通信を行い、ツール呼び出しをホストされたエンドポイントに転送します。クライアントがカスタム HTTP ヘッダーを送信できない場合や、サーバーをコンテナーで実行したい場合に使用してください。

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "github:haljishi/vidwords-mcp"],
      "env": { "VIDWORDS_API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}

このリポジトリから直接実行してください。プロキシは npm に公開されていないため、npx @vidwords/mcp だけでは解決できません。

docker build -t vidwords-mcp .
docker run --rm -i -e VIDWORDS_API_TOKEN=YOUR_API_TOKEN vidwords-mcp

ツールのスキーマはプロキシ内にインラインで定義されているため、認証情報がなくても initialize と tools/list は応答します。リソースの検出もローカルで行われ、ツール、プロンプト、または UI リソースがリクエストされた時点でアップストリームに接続します。 プロキシは分析およびアカウントの MCP Apps リソースも公開します。互換性のあるホストではインタラクティブカードを表示でき、分析カードには Show full analysis が含まれます。UI リソースの読み取りとツール呼び出しには、同じ認証済みアップストリームが使われます。構造化された結果は変更されずに渡されます。

VIDWORDS_API_TOKEN を指定せずに呼び出すと、ハンドシェイクに失敗する代わりに、内容を確認できるエラーが返されます。本番環境以外のインスタンスを指定する場合は、VIDWORDS_MCP_URL でエンドポイントを上書きできます。

汎用の mcp-remote ブリッジも使用できます。

{
  "mcpServers": {
    "vidwords": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://vidwords.com/mcp",
               "--header", "Authorization:${VIDWORDS_MCP_AUTH}"],
      "env": { "VIDWORDS_MCP_AUTH": "Basic YOUR_API_TOKEN" }
    }
  }
}

すぐに使える設定ファイルは examples/ にあります。

---

14 個のツール

利用料金は 2 種類の残高で支払います。Cloud Request は動画 1 本の文字起こしの取得に使い、AI Units はフレームの読み取りと音声の文字起こしに使います。新しいフレーム分析では、それぞれの種類の料金が発生します。 文字起こしに 1 Cloud Request、さらに動画 1 分あたり AI Units が必要です。アカウントがすでに取得した動画は ライブラリに保存され、再度読み取るのは無料です。別の時間範囲や別のページを読む場合も、取得後に検索する場合も同様です。料金が発生する結果には、請求額が charged として表示されます。

ツール	機能	料金
search_transcript	動画内で特定の話題が語られている箇所を検索します。動画 1 本、または最大 25 本のリストを指定できるため、1 回の呼び出しでチャンネル全体に関する質問に回答できます。該当箇所を、タイムスタンプ、引用文脈、youtube.com/watch?v=…&t=…s の詳細リンクとともに返します。from／to は任意です。	新しい動画 1 本につき 1 Cloud Request
get_transcript	最大 25 本の動画の文字起こし、または 2 つのタイムコード間の範囲の文字起こしを取得します。lang で字幕トラックを指定し、maxChars で長い文字起こしをページ分割できます。source: "audio" を指定すると、音声そのものを文字起こしします。	新しい動画 1 本につき 1 Cloud Request
translate_transcript	動画の文字起こしを AI で任意の言語に 1 行ずつ翻訳します。各行のタイムスタンプはそのまま保持されるため、元の文字起こしと同じように読み、引用し、ダウンロードできます。動画に字幕のない言語への翻訳（その場合、get_transcript は language_unavailable と aiTranslation の案内を返します）、または音声の文字起こしの翻訳に使用します。estimateOnly: true を指定すると、翻訳せずに料金のみを返します。	翻訳が成功した場合のみ、動画の 1 分あたり 2 AI Units。再度開く場合は無料 · 新しい動画には 1 Cloud Request も必要
search_library	アカウントがすでに保存したすべての文字起こしを対象に、タイムスタンプと詳細リンク付きで全文検索します。	無料
list_library	アカウントが保存した動画を新しい順に表示し、直近で完了した分析 ID も返します。	無料
list_analyses	保存済みの AI Watch 分析を、ID、ステータス、結果リンクとともに表示します。ページネーションと動画による絞り込みに対応しています。	無料
list_languages	動画にある字幕トラックと、それぞれが自動生成（音声）かアップロード（翻訳の可能性あり）かを表示します。	無料
list_channel_videos	チャンネルのハンドル、URL、または UC… ID を、最近のアップロード動画に対応付けます。	1 Cloud Request · Starter 以上
list_watchlists	アカウントの Radar ウォッチリストと、それぞれに記録された動画数を表示します。	無料
watchlist_activity	1 つのウォッチリストについて、Radar が記録した最新のアップロード動画を表示します。	無料
account	プランと 2 種類の残高を表示するため、エージェントは実行前に作業の料金を確認できます。	無料
analyze_video	フレーム単位の分析を開始します。字幕だけでなく、スライド、グラフ、デモ、画面上のテキストも分析します。すぐに analysisId を返します。mode は quick、smart、deep、auto のいずれかです。十分な AI Units があれば、どのプランでも Deep を実行できます。estimateOnly: true を指定すると、分析を開始せずに料金のみを返します。	1 Cloud Request、さらに動画 1 分あたり AI Units：Quick 2.8、Standard 4、Deep 30 · 料金見積もりは無料
get_analysis	完了した分析を読み込みます。概要、チャプター、要点、タイムスタンプ付きの根拠、手順が含まれます。analysisId を省略すると、直近で完了した結果を開きます。waitSeconds（最大 25）を指定すると、準備ができるまで呼び出しを保留できるため、ポーリングは不要です。	無料
ask_video	完了した分析について質問します。引用は保存された根拠と照合され、検証できないものは除外されます。	質問 1 件につき 6 AI Units

まずライブラリを確認する

search_library と list_library は、アカウントがすでに保存した内容を無料で読み取ります。動画を再取得する前に ライブラリを検索するエージェントなら、「先週見たインタビューで価格について何と言っていたか」という質問にも、 料金をかけず、余分な往復もなく回答できます。

get_transcript より search_transcript を優先してください

どちらも新しい動画ごとに Cloud Request を 1 回消費するため、料金面で選ぶ理由はありません。理由はコンテキストです。 「この2時間のインタビューでは、価格について何と言っていましたか？」と尋ねると、get_transcript は約 20,000語を返します。そのうち価格についての部分はおそらく300語ほどです。価格に関するその300語は、 関係のない19,700語と注意を奪い合うことになり、回答の質が下がり、生成も遅く、高くつきます。

search_transcript は、一致した箇所だけをディープリンク付きで返します。エクスポート、差分、コーパスなど、 本当に全文が必要な場合に get_transcript を使ってください。

動画全体ではなく、範囲を指定してください

どちらの文字起こしツールも、任意の from と to タイムコードを指定できます。秒数（615）、m:ss （10:20）、または h:mm:ss（1:02:13）を使います。

{ "videos": ["dQw4w9WgXcQ"], "from": "10:20", "to": "11:00" }

これらはツールが出力する形式と同じなので、回答に含まれるタイムスタンプを次の質問にそのまま貼り付けられます。 解析できないタイムコードは、何も取得する前に拒否されるため、入力ミスをしても料金は発生しません。動画全体へ 暗黙のうちに範囲が広がることもありません。

範囲を推測するのではなく、長い文字起こしをページ分割してください

get_transcript は maxChars を受け取ります。結果が途中で切れた場合は truncated: true と、 続きを取得するための秒数を示す nextFrom が返されます。これを from として渡してください。切り取りは常に 字幕の区切りで行われ、最初のページ以降は、ライブラリにすでにある動画の再読み込みなので無料です。

{ "videos": ["dQw4w9WgXcQ"], "maxChars": 20000 }

取得した言語と、その理由

字幕トラックの言語は、必ずしも話されている言語とは限りません。自動生成トラックは音声を書き起こしますが、 アップロード済みトラックは翻訳の場合があります。動画によっては、コミュニティによる翻訳が12言語分あり、 実際に話されている言語のトラックがないこともあります。そのため、すべての文字起こしには、どのような理由で そのトラックが選ばれたかが示されます。

• selectionReason：requested、spoken_language（音声と一致）、caption_fallback （音声と一致することが確認されたトラックがない場合。可読性を優先し、英語があれば選択します）、 translated、または audio_transcription。

• spokenLanguage：判明している場合は話されている言語。不明な場合は推測せず null です。

• lang はトラックを指定します。動画にその言語のトラックがない場合、get_transcript は language_unavailable と、利用可能な言語を示す availableLanguages を返し、料金は発生しません。

• source: "audio" は字幕を読む代わりに、話された内容を文字起こしします。すべての字幕が翻訳の場合に、 元の言葉を取得する方法です。料金は通常の音声文字起こしと同じで、動画1分あたり AI Units を3消費し、 Cloud Request に加算されます。この指定を渡すことが同意となります。

• 希望する言語のトラックがなく、YouTube でもその言語に翻訳できない場合は、translate_transcript を使うと、 AI が文字起こしを任意の言語に翻訳します。タイムスタンプは維持されます（1分未満の端数を切り上げて1分あたり AI Units を2消費し、成功した場合に限り1回だけ課金されます。再度読み込むのは無料です）。

list_languages は、すでに保存されている情報をもとに、同じ質問に無料で回答します。

チャンネル全体を1回の呼び出しで検索する

search_transcript はリストを受け取ります。これを使うと、動画ごとにリクエストを往復させずに「このチャンネルは X について何と言っていましたか？」と尋ねられます。まず list_channel_videos から ID を取得してください。

{ "video": ["VIDEO_ID_1", "VIDEO_ID_2", "VIDEO_ID_3"], "query": "pricing" }

新しい動画ごとに通常どおり Cloud Request が1回課金されます。利用できない動画があっても呼び出し全体は失敗せず、 その動画は個別の行に報告されます。他の動画は取得され、その分の料金も発生しているため、結果は引き続き取得できます。

字幕だけでなく、映像も読み取ります

analyze_video は、スライド、グラフ、コードサンプル、画面上のテキストなど、音声では読み上げられない内容も確認します。続いて ask_video が保存された分析結果に基づいて回答し、表示する前にすべての引用を検証します。映像に関する主張は実際に記録されたフレームと一致する必要があり、音声に関する主張は実際の文字起こしの該当箇所に対応していなければなりません。検証に通らないものは除外され、何も残らない場合は、自信ありげな推測をするのではなく、根拠が不十分だと回答します。

拒否は流暢な回答よりデモとして見劣りするため、ときには不便です。それでも、人間の読者が持つ懐疑心なしに、指示された内容をそのまま繰り返すエージェントにこの機能を使わせるには、これが安全な唯一の方法です。

---

認証、料金、制限

• トークンを貼り付けた場合は、Bearer ではなく Basic を使ってください。 トークンはそのまま送信します。user:pass のペアを Base64 エンコードする必要はありません。サインイン済みのクライアントは自身の認証情報を使うため、これは該当しません。
• 最初にメールアドレスを確認してください。 確認リンクをクリックするまでは、すべての呼び出しが {"error":"email_unverified"} を伴う 403 を返します。新しいアカウントで最初に呼び出す際によくある失敗です。
• 残高は REST API およびウェブサイトと共有されます。Cloud Request 1 回で文字起こしを 1 件新たに作成します。フレーム分析では Cloud Request 1 回と AI Units を消費し、音声の文字起こしでは Cloud Request に加えて AI Units を消費します。実行開始前に拒否された場合、料金はかかりません。また、estimateOnly: true を指定した analyze_video では、無料で料金を見積もれます。
• プランごとの 1 分あたりのレート制限： Free は 60 回、Starter は 200 回、Pro は 500 回、Team は 1,000 回です。サーバーはステートレスのため、クライアントは呼び出しのたびに initialize を再実行し、1 回のツール呼び出しで複数のリクエストが発生します。analyze_video には 1 分あたり開始 10 回という独自の上限があり、REST ルートと共有されます。
• RapidAPI トークンはここでは拒否されます。 この認証方式は呼び出しごとに課金され、紐づくアカウントもありません。どちらもツール呼び出しセッションには適していません。VidWords API トークンを使ってください。
• 設計上、ステートレスです。 再開可能な SSE ストリームはなく、削除するセッションもありません。すべてのツールは一度の応答で結果を返します。GET と DELETE は HTML の 404 ではなく、JSON-RPC エラーを返します。
• 字幕がない場合、または字幕が不適切な場合。 字幕トラックのない動画では、音声から文字起こしするために transcribeAudio: true を指定してください。存在する字幕（たとえば、アップロードされたすべての翻訳）を置き換えるには、source: "audio" を指定してください。どちらも有料機能で、動画の長さに応じて課金されます。また、明示的に指定されない限り実行されません。

詳しい料金：料金。

---

プロンプト

サーバーは 3 つのプロンプトも公開しており、Claude などのクライアントでは、すぐに使えるアクションとして表示されます。それぞれ、どのツールをどの順序で使うかをモデルに伝え、最も低コストの方法を優先します。

プロンプト	引数	内容
summarize_video	video	利用可能な最も低コストの方法で読み取った、タイムスタンプ付きの動画 1 本の要約。
research_channel	channel、topic	引用された該当箇所とともに、あるチャンネルが特定のトピックについて述べた内容をまとめます。
find_in_my_library	topic	すでに保存されているすべての内容を検索します（無料）。

エージェントスキル

skills/youtube-transcripts/SKILL.md は、このサーバー向けのすぐに使えるエージェントスキルです。ツールの選択、タイムコード範囲、チャンネル全体の検索、料金表、対応すべきエラーコードを、Claude や互換性のあるエージェントが直接読み込める形式でまとめています。

フォルダーをエージェントのスキルディレクトリにコピーしてください。

git clone --depth 1 https://github.com/haljishi/vidwords-mcp
cp -r vidwords-mcp/skills/youtube-transcripts ~/.claude/skills/

MCP サーバーが設定済みであることを前提としています（「クイックスタート」を参照）。このスキルを読んだアシスタントが、2 時間分の文字起こし全体をコンテキストに取り込むのではなく、タイムコード範囲を指定して search_transcript を使う方法を把握できるようにするのが目的です。

ドキュメント

• エージェントスキル（SKILL.md）
• YouTube MCP サーバー — 概要
• Claude Code でのセットアップ
• Claude Desktop でのセットアップ
• Cursor でのセットアップ
• ChatGPT でのセットアップ
• Codex CLI でのセットアップ
• REST API ドキュメント

サポート

MCP の機能に関する問題（正常に動作しないツール、設定方法をドキュメント化していないクライアント、より明確にできるスキーマなど）は、こちらでイシューを作成してください。アカウントや請求に関するお問い合わせは、サポートまでご連絡ください。

ライセンス

このリポジトリの内容（ドキュメントおよび設定例）は MIT ライセンスの下で提供されています。ホスト型サービス自体はプロプライエタリであり、VidWords の利用規約が適用されます。

---

独立した製品であり、YouTube または Google とは提携していません。