convez.ai
MCP Server
PPiai

youtube-mcp

PPiai/youtube-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP Server for YouTube Data API v3 - search, trends, channel info, video details

Instalação

$npx convez-ai PPiai/youtube-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

YouTube MCP Server

Model Context Protocol (MCP) server for YouTube Data API v3. Provides tools for searching videos, channels, playlists, getting trending content, video details, comments, and more.

Features

  • Video Search - Search YouTube videos with advanced filters (duration, definition, region, date range, etc.)
  • Channel Search - Find channels by query
  • Video Details - Get comprehensive video information (statistics, content details, topics, etc.)
  • Channel Details - Get channel statistics, branding, topics, and more
  • Trending Videos - Get most popular videos by region and category
  • Video Categories - Browse available video categories
  • Channel Videos - Get recent uploads from a specific channel
  • Playlist Videos - Get videos from any playlist
  • Playlist Search - Search for playlists
  • Video Comments - Get comments on videos
  • Channel by Handle - Look up channels by @username

Installation

git clone https://github.com/PPiai/youtube-mcp.git
cd youtube-mcp
pip install -e .

Or with uv:

uv pip install -e .

Configuration

Requires a YouTube Data API v3 key. Get one from Google Cloud Console.

Copy .env.example to .env and fill in your values:

cp .env.example .env
VariableDefaultDescription
YOUTUBE_API_KEY—Required. YouTube Data API v3 key
MCP_TRANSPORTstreamable-httpstreamable-http (remote service) or stdio (local)
HOST0.0.0.0Bind host (HTTP mode)
PORT8000Bind port (HTTP mode)

Transports

This server supports two transports, selected by MCP_TRANSPORT:

Streamable HTTP (remote service — default)

Runs as a persistent HTTP service on a single port (default 8000).

EndpointMethodPurpose
/mcp/POSTMCP streamable-HTTP endpoint (JSON-RPC)
/healthGETHealth check — returns 200 {"status":"ok"}
MCP_TRANSPORT=streamable-http PORT=8000 youtube-mcp
# MCP endpoint: http://localhost:8000/mcp/
# Health:       http://localhost:8000/health

Note — trailing slash. The MCP endpoint is mounted at /mcp, so POST /mcp returns a 307 redirect to /mcp/. Always point clients at /mcp/ (with the trailing slash) to avoid clients that don't follow redirects on POST.

Connecting an MCP client to the remote endpoint (e.g. mcp.json / Claude Desktop style config):

{
  "mcpServers": {
    "youtube": {
      "type": "streamable-http",
      "url": "https://<your-domain>/mcp/"
    }
  }
}

Quick test with curl:

# Health
curl https://<your-domain>/health

# Initialize (note: streamable-HTTP replies with an SSE stream)
curl -X POST https://<your-domain>/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# Call a tool
curl -X POST https://<your-domain>/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_videos","arguments":{"query":"ai news","max_results":2}}}'

⚠️ Security. The HTTP endpoint has no built-in authentication — anyone who can reach the URL can issue requests and consume your YouTube API quota. Put it behind an authenticating reverse proxy / network policy, or keep it on a private network. Do not expose it publicly without protection.

stdio (local)

Launched on-demand by a local client (e.g. via uvx):

mcp_servers:
  youtube:
    command: "uvx"
    args: ["youtube-mcp"]
    env:
      YOUTUBE_API_KEY: "your_api_key_here"
      MCP_TRANSPORT: "stdio"
    timeout: 120
    connect_timeout: 60

Deploy (EasyPanel / Docker)

Build and run as a container:

docker build -t youtube-mcp .
docker run -p 8000:8000 -e YOUTUBE_API_KEY="your_api_key_here" youtube-mcp

On EasyPanel, set YOUTUBE_API_KEY as a service environment variable (not a build-arg), expose port 8000, and point the MCP client to https://<your-domain>/mcp.

Available Tools

ToolDescription
search_videosSearch videos with filters
search_channelsSearch channels
get_video_detailsGet detailed video info
get_channel_detailsGet detailed channel info
get_trending_videosGet trending videos by region
get_video_categoriesGet video categories
get_channel_videosGet channel's recent videos
get_playlist_videosGet playlist videos
search_playlistsSearch playlists
get_video_commentsGet video comments
get_channel_by_handleGet channel by @handle

Example Queries

  • "Search for videos about AI news from the last week"
  • "Get trending videos in Brazil (BR)"
  • "Find channels about programming tutorials"
  • "Get details for video dQw4w9WgXcQ"
  • "Get comments on a viral video"
  • "Find playlists about machine learning"

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run the server locally over HTTP and smoke-test it
MCP_TRANSPORT=streamable-http youtube-mcp &
curl http://localhost:8000/health

No automated test suite yet — pytest is wired up in the dev extra but there are no tests under a tests/ directory. Contributions welcome.

License

MIT

Ver o original no GitHub

Bom para

Relacionados