YouTube MCP

中文文档

YouTube MCP is a Model Context Protocol server for extracting video-platform metadata and context from YouTube and BiliBili. It is designed for Claude, Cursor, VS Code, and other MCP-compatible agents that need searchable video context, subtitles, comments, playlists, streams, danmaku, and live-room metadata.

The server runs locally over stdio and does not require a browser extension or a hosted backend.

Features

• Search videos, channels, playlists, anime/PGC entries, and BiliBili media results.
• Resolve arbitrary supported URLs or IDs with detect_url and resolve_url.
• Extract video metadata, thumbnails, playability status, related items, tags, and available stream URLs or manifests.
• Fetch subtitles and convert them to raw, json, text, srt, or vtt.
• Fetch YouTube comments and BiliBili comments.
• Fetch BiliBili danmaku for regular videos and PGC episodes.
• Fetch YouTube playlists, BiliBili favorites, BiliBili collections, and BiliBili PGC season lists.
• Fetch YouTube channel and BiliBili uploader metadata with recent videos.
• Fetch YouTube live-video metadata and BiliBili live-room stream information.
• Fetch YouTube SponsorBlock skip segments.
• Expose MCP tools, resources, and prompt templates.

Supported Inputs

Platform	Supported IDs and URLs
YouTube	watch URLs, youtu.be URLs, shorts URLs, live URLs, video IDs, playlist IDs/URLs, channel IDs, handles, channel URLs
BiliBili	BV IDs, AV IDs, video URLs, ep IDs/URLs, ss IDs/URLs, favorite ml IDs/URLs, space collection URLs, live room IDs/URLs

Limitations

• The project does not bypass paid content, DRM, private videos, region restrictions, age gates, or account permissions.
• If you provide cookies through environment variables, the server can parse content that the underlying platform API returns for that account.
• YouTube danmaku-style comments are not supported.
• BiliBili subtitle translation is not supported.
• Network-facing platform behavior changes frequently; live integration tests are available but disabled by default.

Installation

Install dependencies with uv:

uv sync

Run the MCP server locally:

uv run youtube-bilibili-mcp

The command starts a stdio MCP server. It is normally launched by an MCP client rather than run directly in a long-lived terminal.

Claude Code Setup

Register the server globally for Claude Code:

claude mcp add-json --scope user youtube-bilibili-mcp \
  '{"type":"stdio","command":"uvx","args":["youtube-bilibili-mcp"],"env":{"YOUTUBE_MCP_REQUEST_TIMEOUT":"30"}}'

Check the connection:

claude mcp get youtube-bilibili-mcp

Claude Desktop Setup

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "youtube-bilibili-mcp": {
      "command": "uvx",
      "args": [
        "youtube-bilibili-mcp"
      ],
      "env": {
        "YOUTUBE_MCP_REQUEST_TIMEOUT": "30"
      }
    }
  }
}

An editable example is available at examples/mcp-config.json.

Configuration

Environment variable	Description
YOUTUBE_MCP_USER_AGENT	Optional custom user agent
YOUTUBE_MCP_REQUEST_TIMEOUT	Request timeout in seconds, default 30
YOUTUBE_MCP_HTTP_PROXY	Optional HTTP proxy URL
YOUTUBE_MCP_YOUTUBE_COOKIES	Optional YouTube cookie header for account-enabled content
YOUTUBE_MCP_BILIBILI_COOKIES	Optional BiliBili cookie header for account-enabled content

Do not commit cookie values, API credentials, or proxy credentials.

MCP Tools

Tool	Purpose
list_services	List supported platforms and feature flags
detect_url	Detect platform and resource type for a URL or ID
resolve_url	Auto-detect and call the matching extractor
search_videos	Search videos or media entries
get_suggestions	Return search suggestions
get_trending	Return trending, popular, or ranking entries
get_video_info	Extract metadata, streams, subtitles, and related context
get_channel_info	Extract channel/uploader metadata and recent videos
get_playlist_info	Extract playlist, favorite, collection, or PGC season entries
get_subtitles	List or fetch subtitles in multiple output formats
get_comments	Fetch comments
get_danmaku	Fetch BiliBili danmaku
get_live_info	Extract live-room or live-video information
get_skip_segments	Fetch YouTube SponsorBlock skip segments

MCP Resources

Resource	Purpose
video://services	Supported service capability matrix
video://service/{platform}	Detailed platform capability notes
video://url/{url}	URL detection result as resource context

MCP Prompts

Prompt	Purpose
summarize_video	Guide an agent through metadata, subtitles, comments, and skip segments
research_channel	Guide an agent through channel/uploader research

Examples

Ask your MCP client:

Use youtube-bilibili-mcp to resolve https://www.bilibili.com/bangumi/play/ep693247

Use youtube-bilibili-mcp to search YouTube for "lofi study music" and return 5 results.

Use youtube-bilibili-mcp to fetch subtitles for dQw4w9WgXcQ as text.

Development

Run local checks:

uv run ruff check src tests
uv run pytest

Run live extractor tests:

YOUTUBE_MCP_LIVE_TESTS=1 uv run pytest tests/test_live_extractors.py

Build the package:

uv build

Publishing

Publishing notes and an MCP Registry template are available in:

• docs/publishing.md
• examples/server.json

License

MIT License. See LICENSE.