Youtube Caption Mcp

this is vibe coded BE CAREFUL

YouTube Caption MCP Server

Vive An MCP server for Cursor to retrieve YouTube video captions. Access YouTube video caption information without requiring an API key.

Features

• No API Key Required: Access YouTube's internal API using the youtube-js library
• Multilingual Support: Automatic detection and retrieval of available caption languages
• Format Conversion: Caption output in Raw, SRT, and VTT formats
• Caching: In-memory caching for improved performance
• Claude Integration: Seamless integration via MCP protocol

Installation

Install from NPM

npm install -g @iamyosuke/youtube-caption-mcp

Build from Source

git clone https://github.com/iamyosuke/youtube-caption-mcp.git
cd youtube-caption-mcp
npm install
npm run build

Cursor Configuration

Add the following to your Cursor configuration file (.cursor/mcp.json):

{
  "mcpServers": {
    "youtube-caption-mcp": {
      "command": "npx",
      "args": ["-y", "youtube-caption-mcp", "--stdio"],
      "env": {
        "CACHE_ENABLED": "true",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Available Tools

1. getvideoinfo

Retrieves basic information about a YouTube video.

Parameters:

• video_id (required): YouTube video ID or URL

Example:

{
  "video_id": "dQw4w9WgXcQ"
}

2. getcaptionslist

Retrieves a list of available captions for a video.

Parameters:

• video_id (required): YouTube video ID or URL

Example:

{
  "video_id": "dQw4w9WgXcQ"
}

3. download_captions

Downloads captions for a specified video.

Parameters:

• video_id (required): YouTube video ID or URL
• lang (optional): Caption language code (default: "ja")
• format (optional): Output format - "raw", "srt", "vtt" (default: "raw")

Example:

{
  "video_id": "dQw4w9WgXcQ",
  "lang": "ja",
  "format": "srt"
}

4. searchvideoswith_captions

Searches for videos with captions.

Parameters:

• query (required): Search query
• lang (optional): Caption language filter
• limit (optional): Maximum number of search results (1-50, default: 10)

Example:

{
  "query": "programming tutorial",
  "lang": "en",
  "limit": 5
}

Supported URL Formats

The following YouTube URL formats are supported:

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://www.youtube.com/embed/VIDEO_ID
• VIDEO_ID (11-character video ID)

Environment Variables

| Variable Name | Default Value | Description | |---------------|---------------|-------------| | CACHE_ENABLED | true | Enable/disable caching | | CACHE_DEFAULT_TTL | 3600 | Default cache retention time (seconds) | | CACHE_MAX_KEYS | 1000 | Maximum number of cache keys | | LOG_LEVEL | info | Log level (debug, info, warn, error) |

Development

Setup Development Environment

npm install

Start Development Server

npm run dev

Run Tests

npm test

Build

npm run build

Lint & Format

npm run lint
npm run format

License

MIT License

Contributions

Pull requests and issue reports are welcome.

Disclaimer

Note: This project was vibe coded for three hours on a weekend and hasn't been thoroughly tested. Use in production environments at your own risk.

Caution

• Please use this tool in accordance with YouTube's Terms of Service
• Handle copyrighted content appropriately
• Be mindful of rate limits when sending many requests

Troubleshooting

Common Issues

1. Video Not Found

• Check if the video ID or URL is correct
• Check if the video is publicly available

1. Cannot Get Captions

• Check if the video has captions
• Check if the specified language captions are available

1. Slow Performance

• Check if caching is enabled
• Check your network connection

Checking Logs

To view detailed logs, set the environment variable LOG_LEVEL=debug:

LOG_LEVEL=debug npx @iamyosuke/youtube-caption-mcp

---

YouTube字幕MCPサーバー

Cusor 向けのYouTube動画字幕取得MCPサーバーです。APIキー不要でYouTube動画の字幕情報を取得できます。

特徴

• APIキー不要: youtube-jsライブラリを使用してYouTubeの内部APIにアクセス
• 多言語対応: 利用可能な字幕言語の自動検出と取得
• フォーマット変換: Raw、SRT、VTT形式での字幕出力
• キャッシュ機能: パフォーマンス向上のためのインメモリキャッシュ
• Claude統合: MCPプロトコルによるシームレスな連携

インストール

NPMからインストール

npm install -g @iamyosuke/youtube-caption-mcp

ソースからビルド

git clone https://github.com/iamyosuke/youtube-caption-mcp.git
cd youtube-caption-mcp
npm install
npm run build

Cursor設定

Cursorの設定ファイル（.cursor/mcp.json）に以下を追加してください：

{
  "mcpServers": {
    "youtube-caption-mcp": {
      "command": "npx",
      "args": ["-y", "youtube-caption-mcp", "--stdio"],
      "env": {
        "CACHE_ENABLED": "true",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

利用可能なツール

1. getvideoinfo

YouTube動画の基本情報を取得します。

パラメータ:

• video_id (必須): YouTube動画IDまたはURL

例:

{
  "video_id": "dQw4w9WgXcQ"
}

2. getcaptionslist

動画で利用可能な字幕一覧を取得します。

パラメータ:

• video_id (必須): YouTube動画IDまたはURL

例:

{
  "video_id": "dQw4w9WgXcQ"
}

3. download_captions

指定された動画の字幕をダウンロードします。

パラメータ:

• video_id (必須): YouTube動画IDまたはURL
• lang (オプション): 字幕の言語コード（デフォルト: "ja"）
• format (オプション): 出力形式 - "raw", "srt", "vtt"（デフォルト: "raw"）

例:

{
  "video_id": "dQw4w9WgXcQ",
  "lang": "ja",
  "format": "srt"
}

4. searchvideoswith_captions

字幕付きの動画を検索します。

パラメータ:

• query (必須): 検索クエリ
• lang (オプション): 字幕の言語フィルタ
• limit (オプション): 検索結果の最大数（1-50、デフォルト: 10）

例:

{
  "query": "プログラミング チュートリアル",
  "lang": "ja",
  "limit": 5
}

対応URL形式

以下のYouTube URL形式に対応しています：

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://www.youtube.com/embed/VIDEO_ID
• VIDEO_ID (11文字の動画ID)

環境変数

| 変数名 | デフォルト値 | 説明 | |--------|-------------|------| | CACHE_ENABLED | true | キャッシュ機能の有効/無効 | | CACHE_DEFAULT_TTL | 3600 | デフォルトキャッシュ保持時間（秒） | | CACHE_MAX_KEYS | 1000 | 最大キャッシュキー数 | | LOG_LEVEL | info | ログレベル（debug, info, warn, error） |

開発

開発環境のセットアップ

npm install

開発サーバーの起動

npm run dev

テストの実行

npm test

ビルド

npm run build

リント・フォーマット

npm run lint
npm run format

ライセンス

MIT License

貢献

プルリクエストやイシューの報告を歓迎します。

免責事項

注意: このプロジェクトは週末の3時間で作成されたものであり、十分なテストが行われていません。本番環境での使用は自己責任でお願いします。

注意事項

• このツールはYouTubeの利用規約に従って使用してください
• 著作権保護されたコンテンツの適切な取り扱いにご注意ください
• 大量のリクエストを送信する際は、レート制限にご注意ください

トラブルシューティング

よくある問題

1. 動画が見つからない

• 動画IDまたはURLが正しいか確認してください
• 動画が公開されているか確認してください

1. 字幕が取得できない

• 動画に字幕が存在するか確認してください
• 指定した言語の字幕が利用可能か確認してください

1. パフォーマンスが遅い

• キャッシュが有効になっているか確認してください
• ネットワーク接続を確認してください

ログの確認

詳細なログを確認するには、環境変数 LOG_LEVEL=debug を設定してください。

LOG_LEVEL=debug npx @iamyosuke/youtube-caption-mcp

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [iamyosuke](https://github.com/iamyosuke)
- **Source:** [iamyosuke/youtube-caption-mcp](https://github.com/iamyosuke/youtube-caption-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.