MMCPMarkets
UY

umbertotancorre/youtube-mcp-cli

Developer tools
33 stars 3 forks Quality 78 Trend 34MIT
Repository Install

MCP server and CLI tool that gives AI agents access to YouTube

Overview

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 - MCP: @umbertotancorre/youtube-mcp - CLI: @umbertotancorre/youtube-cli download_video and download_audio are fully self-contained. yt-dlp and ffmpeg are downloaded automatically on npm install. Add this to your MCP client config (e.g. claude_desktop_config.json): All tools appear automatically. No install needed, npx handles it on first run. Downloads always go to the platform-native Downloads folder: This is an npm workspaces monorepo with three packages:

README

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:

All locally. No API keys required.

Table of Contents

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

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

youtube-cli download                     Download video to Downloads
youtube-cli download  --quality hd1080   Choose quality
youtube-cli download  --audio            Download audio only (mp3)
youtube-cli download  --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.

View this README on GitHub

Install

npx -y @umbertotancorre/youtube-mcp

Configuration

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