youtube-ai 0.2.2

YTAI: Python YouTube SDK, CLI, and MCP server without user-supplied API keys

YTAI: Python YouTube SDK, CLI and MCP Server

YTAI is a Python SDK, command-line interface, and MCP server for YouTube search, metadata, transcripts, comments, channels, and media downloads without a user-supplied YouTube Data API key.

It uses YouTube's public InnerTube interface through curl_cffi browser impersonation, dynamically refreshes web-client configuration, and caches public responses locally with SQLite and orjson.

YTAI is an independent project. It is not affiliated with or endorsed by YouTube or Google. Use it in accordance with applicable terms, copyright law, and local regulations.

Contents

• Features
• Installation
• Quick start
• Downloads
• MCP server
• FastAPI server
• Documentation
• Testing
• Limitations

Features

• Search videos, channels, and playlists with filters and pagination
• Retrieve metadata, likes, captions, related videos, and comments
• Fetch timestamped transcripts with language selection and XML fallback
• Inspect channels, recent uploads, and popular videos
• Download full video with audio, video-only, audio-only, or a time range
• Resume interrupted downloads with ranged transfers and per-chunk retries
• Cache responses in SQLite with operation-specific TTLs
• Use the Python SDK, Rich-powered ytai CLI, nine read-only MCP tools, or the FastAPI service

Installation

Requirements:

• Python 3.10 or newer
• No separate FFmpeg installation is required for downloads; YTAI bundles FFmpeg through imageio-ffmpeg

Clone and install the project:

git clone https://github.com/vibheksoni/youtube-ai.git
cd youtube-ai
python -m pip install -e .

Install development dependencies when running tests:

python -m pip install -e ".[dev]"

FFmpeg is bundled automatically for Windows, macOS, and Linux when you install YTAI. If you prefer a system build, it is used when ffmpeg is on PATH. To pin an explicit binary, set YTAI_FFMPEG_PATH to its full path:

$env:YTAI_FFMPEG_PATH = "C:\tools\ffmpeg\bin\ffmpeg.exe"

YTAI_API_KEY is an optional offline fallback when live configuration cannot be fetched. It is read from the environment and is never stored in the repository.

For environment setup and first-run guidance, continue with Getting Started.

Quick start

Use YouTubeClient as a context manager so its HTTP session is closed cleanly:

from youtube_ai import YouTubeClient

with YouTubeClient() as client:
    results = client.search("python tutorial", limit=5, filter_type="video")
    for item in results["results"]:
        print(item["title"], item["url"])

    video = client.get_video("dQw4w9WgXcQ")
    print(video["details"]["title"])
    print(video["details"]["likes"])

    transcript = client.get_transcript("dQw4w9WgXcQ", language_codes=("en",))
    for segment in transcript["snippets"][:5]:
        print(f"{segment['start']:.1f}s: {segment['text']}")

Common CLI commands:

ytai search "python tutorial" --limit 10 --filter video
ytai video dQw4w9WgXcQ
ytai transcript dQw4w9WgXcQ --lang en
ytai comments dQw4w9WgXcQ --limit 20

See the Python API reference and CLI reference for complete signatures and commands.

Downloads

Inspect available qualities, codecs, stream sizes, and modes before downloading:

ytai download-options dQw4w9WgXcQ

Download a full video with audio:

ytai download dQw4w9WgXcQ --quality 720p --output ./downloads

Video-only, audio-only, and clipping are opt-in:

ytai download dQw4w9WgXcQ --quality 1080p --video-only
ytai download dQw4w9WgXcQ --audio-only
ytai download dQw4w9WgXcQ --quality 360p --start 30 --end 90

The SDK also exposes VideoQuality, DownloadMode, get_download_options(), and download_video(). See the download API and download example.

MCP server

Start the FastMCP server:

python mcp/server.py

It exposes nine read-only tools for search, video data, transcripts, streaming formats, comments, channels, and popular videos. Media downloading is intentionally available through the SDK and CLI only.

See MCP Server Setup for client configuration and tool parameters.

FastAPI server

Start the versioned HTTP API:

ytai-api

Swagger UI is available at http://127.0.0.1:8000/docs. The API covers search, video data, transcripts, comments, formats, download options, channels, and popular videos. See the FastAPI Server Guide for routes, curl examples, configuration, validation, and deployment guidance.

Documentation

• Getting Started: prerequisites, installation, and first workflows
• API Reference: public classes, functions, enums, and return shapes
• CLI Reference: every ytai command and option
• MCP Server: server setup, tools, parameters, and errors
• FastAPI Server: HTTP routes, OpenAPI docs, configuration, and examples
• Examples: runnable search, metadata, transcript, comment, channel, download, and MCP scripts

Testing

The end-to-end suite calls the real YouTube InnerTube and Google Video boundaries. It covers search, transcripts, comments, channels, MCP tools, CLI commands, download modes, clipping, resumable ranges, and ffmpeg output streams.

pytest tests/test_e2e.py -v

Limitations

• Private, members-only, and most age-restricted content is unavailable without authentication.
• InnerTube endpoints and renderer structures can change without notice.
• Channel uploads currently return the first available page.
• Adaptive full-video downloads and clipping use the bundled FFmpeg executable (or YTAI_FFMPEG_PATH when configured).
• Playlist contents are not currently fetched.

Credits

YTAI acknowledges these public projects as references for protocol details, format mappings, and implementation ideas:

• YouTube.js
• innertube-go
• youtube-transcript-api
• yt-dlp

License

MIT, as declared in pyproject.toml.