@mrsknetwork/ytmcp

YouTube MCP (@mrsknetwork/ytmcp)

A Model Context Protocol (MCP) server that provides AI assistants (including Claude Desktop, Cursor, VS Code, and Antigravity) with tools for interacting with public and private YouTube data.

This server interfaces securely with the official YouTube Data API v3 and supports a tiered authentication system for maximum flexibility and reliability.

Features and Capabilities

• Tiered Authentication System:
  • API Key Mode: Instantly access public data using a provisioned API key.
  • OAuth2 Mode: Access private user data (subscriptions, memberships, playlists) with automatic token refresh and incremental authorization.
  • Guest Mode: The server remains operational without credentials. Scraper-dependent tools, such as download_video_caption, function via yt-dlp extraction methods.
• Security: Implements protected OAuth callbacks, automated server timeouts, and a built-in revoke_authentication tool for secure session termination.
• Transcripts: Extracts clean-text video transcripts directly, bypassing API restrictions via yt-dlp integration.

Installation and Quick Start

The recommended initialization method utilizes an existing YouTube Data API Key. This provides access to all public data endpoints (Search, Details, Captions).

Add the following configuration to your MCP client:

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mrsknetwork/ytmcp@latest",
        "YOUR_GOOGLE_API_KEY"
      ]
    }
  }
}

Advanced Configuration: OAuth 2.0

Accessing private data requires OAuth 2.0 configuration.

1. Acquire Credentials

• Navigate to the Google Cloud Console.
• Create a project and enable the YouTube Data API v3.
• Navigate to APIs & Services > Credentials.
• Create an OAuth 2.0 Client ID (Application type: "Web application").
• Specify the Authorized Redirect URI: http://localhost:3000/oauth2callback.

2. Client Configuration

Define the credentials within your client's environment variables. The server will detect these variables, prioritize them over the positional API Key argument, and initiate the OAuth2 authorization flow upon the first tool execution.

{
  "mcpServers": {
    "youtube-mcp": {
      "command": "npx",
      "args": ["-y", "@mrsknetwork/ytmcp@latest"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-google-oauth-client-id",
        "GOOGLE_CLIENT_SECRET": "your-google-oauth-client-secret"
      }
    }
  }
}

Note: The initial OAuth tool invocation will generate a secure URL requiring explicit browser authorization.

Available Tools Reference

Tool Name	Description	Requires Authentication
download_video_caption	Extracts clear-text video transcripts via yt-dlp.	No (Guest Mode Supported)
search_youtube_content	Performs queries for videos, channels, and playlists.	API Key or OAuth
get_video_details	Retrieves video statistics, descriptions, and metadata.	API Key or OAuth
get_channel_details	Retrieves channel subscriber metrics and profiles.	API Key or OAuth
get_playlists	Retrieves user or channel playlists.	API Key or OAuth
get_playlist_items	Retrieves the video index within a specified playlist.	API Key or OAuth
get_comment_threads	Retrieves top-level comment threads for a video.	API Key or OAuth
get_comments_replies	Retrieves specific reply threads to top-level comments.	API Key or OAuth
get_subscriptions_list	Retrieves subscription data.	OAuth Only
get_memberships_levels	Retrieves membership pricing tiers for a channel.	OAuth Only
revoke_authentication	Terminates the active session and deletes stored tokens.	OAuth Only

Source Installation and Development

To compile and execute the server directly from source:

• Clone the Repository:

  git clone https://github.com/mrsknetwork/youtube-mcp.git
  cd youtube-mcp
  npm install
  

• Compile the TypeScript Source:

  npm run build
  

• Execute the Server:

  node build/server/index.js "YOUR_API_KEY"
  

  Note: For local development, you can use npm run build && node build/server/index.js.

3. Usage with Docker

[!IMPORTANT] Security Notice: The provided Dockerfile and .dockerignore are configured to exclude your personal .env and tokens.json files. This ensures your credentials are never baked into the image. You must provide them as environment variables at runtime.

The YouTube MCP server is fully compatible with the Docker MCP Toolkit and the Official Docker MCP Registry.

Build the Image

docker build -t ytmcp .

Docker MCP Registry Configuration

If you wish to submit this server to the Official Docker MCP Registry, use the following server.yaml configuration:

name: ytmcp
image: mcp/ytmcp
type: server
meta:
  category: multimedia
  tags:
    - youtube
    - search
    - transcript
about:
  title: YouTube MCP
  icon: https://www.google.com/s2/favicons?domain=youtube.com&sz=64
source:
  project: https://github.com/mrsknetwork/youtube-mcp
  # commit: <latest-commit-hash>
run:
  env:
    GOOGLE_CLIENT_ID: $GOOGLE_CLIENT_ID
    GOOGLE_CLIENT_SECRET: $GOOGLE_CLIENT_SECRET
    GOOGLE_REDIRECT_URI: http://localhost:3000/oauth2callback
config:
  secrets:
    - name: google.client_id
      env: GOOGLE_CLIENT_ID
    - name: google.client_secret
      env: GOOGLE_CLIENT_SECRET

Docker MCP Toolkit Integration (Local)

• Open Docker Desktop and go to the MCP Toolkit dashboard.
• Click Add Server > Image.
• Use the image ytmcp you built locally.
• Set the environment variables in the dashboard.
• Ensure a volume is mounted to persist tokens.json: -v ${PWD}/tokens.json:/app/tokens.json.

4. First-time Authentication

When you run the server for the first time, it will automatically open a Google Login page in your default browser. Authorize the application. Upon success, a tokens.json file will be generated locally so you don't continually need to authenticate.

Note: The authorization server spins up a small local express app strictly on 127.0.0.1:3000 to capture the callback securely.

License

Licensed under the MIT License.