Video Viewer MCP

MCP server for video viewing - download videos, extract subtitles, and capture screenshots.

• Video Download: Download videos from YouTube, Bilibili, and other platforms supported by yt-dlp
• Subtitles Extraction: Get subtitles/captions from downloaded videos (including AI-generated subtitles for Bilibili)
• Danmaku Support: Get bullet comments from Bilibili videos with pagination
• Screenshot Capture: Capture frames at specific timestamps
• Authentication Support: YouTube cookies and Bilibili tokens for members-only content

uv sync
uv run video-viewer-mcp

pip install -e .
video-viewer-mcp

From GitHub Container Registry:

docker pull ghcr.io/xz-dev/video_viewer_mcp:latest
docker run -p 8000:8000 -v video-data:/data ghcr.io/xz-dev/video_viewer_mcp:latest

Build locally:

podman build -t video-viewer-mcp -f Containerfile .
podman run -p 8000:8000 -v video-data:/data video-viewer-mcp

The server exposes both MCP and REST API interfaces on port 8000.

• /mcp - Streamable HTTP transport

• POST /api/download?url=<video_url> - Download a video
• GET /api/download/{job_id} - Get download status
• GET /api/downloads - List all downloads
• GET /api/video-info?url=<video_url> - Query video metadata without downloading
• GET /api/subtitles?url=<video_url> - Get subtitles
• GET /api/danmaku?url=<video_url> - Get danmaku (Bilibili bullet comments)
• GET /api/screenshot?url=<video_url>&timestamp=<time> - Capture screenshot
• GET /api/health - Health check

API documentation available at /docs.

Query video metadata without downloading. Returns concise metadata by default (optimized for AI context understanding).

Default fields:

• id, title, description, duration, chapters
• uploader, channel, upload_date
• width, height, thumbnail
• view_count, like_count, comment_count
• categories, tags

Extra fields (optional):

Use extra_fields parameter to request additional data using dot notation:

Example MCP call:

{
  "url": "https://www.youtube.com/watch?v=xxx",
  "extra_fields": ["formats.resolution", "subtitles"]
}

Configuration via environment variables:

video-viewer-mcp automatically cleans up expired downloaded files to free disk space.

Default Behavior:

• Retention Period: 1 day (24 hours)
• Cleanup Schedule: Daily at 2 AM
• What Gets Cleaned: Completed or failed downloads older than the retention period

Configuration:

Edit ~/.config/video-viewer-mcp/config.json:

{
  "cleanup": {
    "enabled": true,
    "retention_days": 1,
    "schedule": "0 2 * * *"
  }
}

Options:

• enabled (bool): Enable/disable automatic cleanup. Default: true
• retention_days (number): Days to retain files. Default: 1. Supports fractional values (e.g., 0.5 for 12 hours)
• schedule (string): Cron expression defining cleanup time. Default: "0 2 * * *" (2 AM daily). Uses system timezone.

Examples:

Keep files for 7 days, clean at 3 AM:

{
  "cleanup": {
    "retention_days": 7,
    "schedule": "0 3 * * *"
  }
}

Disable cleanup:

{
  "cleanup": {
    "enabled": false
  }
}

What Gets Cleaned:

• ✅ Completed downloads older than retention period
• ✅ Failed downloads older than retention period
• ✅ Associated metadata (job files, URL index entries)

What's Protected:

• ❌ Files currently downloading
• ❌ Files within retention period

File Age Calculation:

Folder age is based on the oldest file's modification time (typically the video download time).

Example:

• Video downloaded: 2 days ago
• Subtitle added: 1 hour ago
• Folder age: 2 days (based on oldest file)

Note: Configuration changes require application restart to take effect.

• Python 3.13+
• ffmpeg (for video processing)
• BBDown + .NET 8.0 (for Bilibili downloads, optional)

Apache-2.0