Skip to main content
Glama
umbertotancorre

youtube-mcp

by umbertotancorre
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

YouTube MCP server and CLI

npm mcp npm cli License: MIT Node

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

Related MCP server: YouTube for AI Agents

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers