License: MIT Python 3.10+

TubeMCP

MCP server that lets AI agents search YouTube and fetch transcripts. Zero config — just install and go.

What is MCP? Model Context Protocol lets AI assistants like Claude call external tools. TubeMCP gives your AI agent the ability to search YouTube and read any video's transcript — useful for summarization, Q&A, research, and content analysis.

Prerequisites

• Python 3.10+ — download

Installation

pip install tubemcp

or

uv tool install tubemcp

Then add it to your client:

Claude Code:

claude mcp add tubemcp -- tubemcp

Claude Desktop — add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tubemcp": {
      "command": "tubemcp"
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "tubemcp": {
      "command": "tubemcp"
    }
  }
}

Windsurf — add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "tubemcp": {
      "command": "tubemcp"
    }
  }
}

What you get

youtube_get_transcript

Fetch the English transcript and metadata for any YouTube video.

Input: A YouTube URL or video ID in any of these formats:

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

Returns:

• video_id — the video ID
• title — video title
• channel_name — channel name
• thumbnail_url — thumbnail URL
• duration_seconds — video duration
• publish_date — publish date
• transcript — full transcript text
• from_cache — whether the result was served from cache

youtube_search

Search YouTube with multiple queries for broader coverage. Results are deduplicated by video ID. Returns metadata only — no transcripts.

Input:

• queries (list[str]) — search queries to run. Use 2–3 from different angles for best results.
• max_results_per_query (int, default 3) — max results returned per query.

Returns a list of results, each containing:

• video_id — the video ID
• title — video title
• channel_name — channel name
• url — video URL
• duration_seconds — video duration

Caching

Transcripts are cached locally in ~/.tubemcp/cache.db (SQLite). Subsequent requests for the same video are served instantly from cache.

Troubleshooting

spawn uvx ENOENT

This means your MCP client can't find the uvx command. Three fixes:

1. uv not installed — Install it: https://docs.astral.sh/uv/getting-started/installation/
2. uv not on PATH — Use the full path to uvx in your config (find yours with which uvx):

   "command": "/Users/you/.local/bin/uvx"
   

3. Switch to pip — Skip uv entirely. Install with pip install tubemcp and use "command": "tubemcp" in your config (see pip installation above).

Verify uv is working:

uvx --version

Development

git clone https://github.com/BlockBenny/tubemcp.git
cd tubemcp
pip install -e ".[dev]"
pytest

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT