Metadata-Version: 2.4
Name: youtube-bilibili-mcp
Version: 0.1.0
Summary: MCP server for extracting public and credential-enabled video platform metadata.
Project-URL: Homepage, https://github.com/JianxunRao/youtube-mcp
Project-URL: Repository, https://github.com/JianxunRao/youtube-mcp
Project-URL: Issues, https://github.com/JianxunRao/youtube-mcp/issues
Author: Jianxun Rao
License-Expression: MIT
License-File: LICENSE
Keywords: bilibili,mcp,metadata,subtitles,video,youtube
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: quickjs>=1.19.0
Description-Content-Type: text/markdown

# YouTube MCP

[中文文档](README_CN.md)

<!-- mcp-name: io.github.JianxunRao/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`:

```bash
uv sync
```

Run the MCP server locally:

```bash
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:

```bash
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:

```bash
claude mcp get youtube-bilibili-mcp
```

## Claude Desktop Setup

Add this to `claude_desktop_config.json`:

```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`](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:

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

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

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

## Development

Run local checks:

```bash
uv run ruff check src tests
uv run pytest
```

Run live extractor tests:

```bash
YOUTUBE_MCP_LIVE_TESTS=1 uv run pytest tests/test_live_extractors.py
```

Build the package:

```bash
uv build
```

## Publishing

Publishing notes and an MCP Registry template are available in:

- [`docs/publishing.md`](docs/publishing.md)
- [`examples/server.json`](examples/server.json)

## License

MIT License. See [`LICENSE`](LICENSE).
