YouTube MCP server and CLI

Zero Setup · No API Key · No Account · Open Source

YouTube is full of knowledge, but it is trapped there. AI agents cannot access it natively. This repo ships two packages that fix that: an MCP server for AI agents and a CLI for the terminal.

• Fetch transcript (plain text or with timestamps)
• Download transcript as .md
• Get video metadata
• Search within captions
• Download video or audio

Available as:

• MCP: @umbertotancorre/youtube-mcp
• CLI: @umbertotancorre/youtube-cli

All locally. No API keys required.

---

Table of Contents

• MCP Server
  • Tools
  • Installation
• CLI
  • Commands
  • Installation
• Development
• Disclaimer
• License

---

MCP Server

Tools

Tool	Description
get_transcript	Fetches the full transcript as plain text
get_transcript_timed	Transcript with [MM:SS] timestamps per segment
download_transcript	Saves transcript as a .md file
download_transcript_timed	Saves transcript as a .md file with timestamps
get_metadata	Returns title, channel, publish date, view count, duration, likes, and description
search_transcript	Searches for a keyword or phrase and returns matching segments with timestamps
download_video	Downloads video+audio as .mp4
download_audio	Downloads audio as .mp3 (or m4a, flac, opus, ...)

download_video and download_audio are fully self-contained. yt-dlp and ffmpeg are downloaded automatically on npm install.

Installation

Method A: let your AI do it

Tell your AI agent:

Add youtube-mcp as an MCP server. Run it with: npx @umbertotancorre/youtube-mcp

Method B: manual config

Add this to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["-y", "@umbertotancorre/youtube-mcp"]
    }
  }
}

All tools appear automatically. No install needed, npx handles it on first run.

---

CLI

Commands

youtube-cli transcript <url>                  Print transcript as plain text
youtube-cli transcript <url> --timestamps     Include [MM:SS] timestamps
youtube-cli transcript <url> --save           Save as .md to Downloads
youtube-cli transcript <url> --language it    Fetch in a specific language

youtube-cli search <url> <query>              Search transcript with timestamps
youtube-cli metadata <url>                    Print title, channel, views, duration
youtube-cli metadata <url> --json             Output as JSON

youtube-cli download <url>                    Download video to Downloads
youtube-cli download <url> --quality hd1080   Choose quality
youtube-cli download <url> --audio            Download audio only (mp3)
youtube-cli download <url> --audio --format flac

youtube-cli completions                       Print bash completion script
youtube-cli completions zsh                   Print zsh completion script

Downloads always go to the platform-native Downloads folder:

OS	Path
macOS	~/Downloads
Linux	$XDG_DOWNLOAD_DIR or ~/Downloads
Windows	%USERPROFILE%\Downloads

Installation

Global install (recommended):

npm install -g @umbertotancorre/youtube-cli
youtube-cli --help

One-off use without installing:

npx @umbertotancorre/youtube-cli transcript dQw4w9WgXcQ

Shell completions (optional):

# bash
source <(youtube-cli completions)

# zsh
youtube-cli completions zsh > ~/.zsh/completions/_youtube-cli

---

Development

This is an npm workspaces monorepo with three packages:

youtube-mcp-cli/
  packages/
    core/     # shared logic (transcripts, metadata, downloads)
    mcp/      # MCP server (@umbertotancorre/youtube-mcp)
    cli/      # CLI tool     (@umbertotancorre/youtube-cli)

npm run build        # build all packages (core, mcp, cli in order)
npm run dev:mcp      # build core, then run MCP server via ts-node
npm run dev:cli      # build core, then run CLI via ts-node

---

Disclaimer

This project only accesses publicly available YouTube data: the same captions, metadata, and streams visible in any browser. It does not bypass authentication, paywalls, or age gates. No API key, account, or login is required.

End users are responsible for complying with YouTube's Terms of Service. The maintainer does not host or operate any service. This is a local tool you run on your own machine.

License

youtube-mcp-cli is fully open source, licensed under the MIT License.