What can you do with this server?

The YouTube MCP server provides production-grade tools for accessing public YouTube data in a quota-aware, AI-friendly way. All listing tools support pagination via nextPageToken/next_page_token, and expensive operations are explicit opt-ins. * Get Video Info (get_yt_video_info): Fetch metadata and transcript for any YouTube video by ID or full URL. * Resolve a Channel (resolve_youtube_channel): Convert a channel handle, URL, or username into a channelId, with optional uploads playlist ID retrieval and strict/best-effort modes. * List Channel Videos (list_youtube_channel_videos): Paginate through a channel's uploads with filtering (excludes Shorts/live by default), multiple ordering strategies, and quota-aware modes. * List Channel Playlists (list_youtube_channel_playlists): Retrieve all public playlists for a given channel. * List Playlist Videos (list_youtube_playlist_videos): Browse videos within any public playlist, with optional Shorts/live filtering. * Search Channel Videos (search_youtube_channel_videos): Keyword search within a specific channel using the YouTube Search API (quota-expensive: ~100 units/page). * List Video Comments (list_youtube_video_comments): Fetch public comment threads for a video, with ordering, reply inclusion, and text format options (may return 403 if comments are disabled). Tools return structured JSON, include quota estimates, and require a YOUTUBE_API_KEY for most operations.

Which integrations are available for this server?

Provides tools for interacting with the YouTube Data API to resolve channel information, list channel videos and playlists, search within channels, and retrieve video metadata, transcripts, and comments.

How do I use YouTube MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@YouTube MCP Summarize the transcript for https://www.youtube.com/watch?v=dQw4w9WgXcQ" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

YouTube MCP

by glonorce

Overview Schema Source Related Servers Discussions Admin

Python

Remote

YouTube MCP (youtube_mcp)

PyPI version Python 3.13+ License: MIT

A Model Context Protocol (MCP) server that provides production-grade YouTube inventory tools (channel resolution, channel videos, channel playlists, playlist videos) designed to be safe-by-default, quota-aware, and AI-friendly.

Repository: https://github.com/glonorce/youtube_mcp PyPI: https://pypi.org/project/glonorce-youtube-mcp/

Naming note:
Repo name: youtube_mcp
Python package / import name: youtube_mcp
MCP entry module: python -m youtube_mcp.server

Prerequisites (PATH)

Make sure these commands work in your terminal (they must be on PATH):

python --version
python -m pip --version
pipx --version (only if you use the pipx-based MCP config)

PATH is the list of folders that your OS searches when you run a command like python or pipx.

If a command is not on PATH, you'll see errors like:
- Windows: executable file not found in %PATH%
- PowerShell: ... is not recognized as the name of a cmdlet

Quick checks (Windows):

where python
where pipx
$env:Path

On Windows:

install Python from https://www.python.org/downloads/
during installation, check "Add Python to PATH"

Install pipx (only if you use the pipx-based MCP config):

python -m pip install --user pipx
python -m pipx ensurepath

Notes:

After pipx ensurepath, restart your terminal/IDE so pipx is available on PATH.
Verify with: pipx --version

Related MCP server: YouTube MCP Server

✨ Available on PyPI

pip install glonorce-youtube-mcp

# run
youtube_mcp

Screenshots

Features

7 MCP tools (1 text-output tool + 6 structured-output tools)
Safe defaults (public data only; shorts/live excluded unless enabled)
Quota-aware design (budgeting + expensive strategies as explicit opt-in)
Tool discovery works in MCP hosts (tools registered with rich docstrings)
Resilient YouTube Data API client (endpoint allowlist, retries, gzip handling)

Tools

This server exposes 7 tools:

get_yt_video_info(video_id_or_url) -> str
- Accepts a raw video id or a full YouTube URL.
- Returns video metadata + transcript (when available).
resolve_youtube_channel(channel_ref, ...) -> dict
list_youtube_channel_videos(channel_ref, ...) -> dict
- Paginated.
- Returns nextPageToken and next_page_token (alias).
list_youtube_channel_playlists(channel_ref, ...) -> dict
- Paginated.
- Returns nextPageToken and next_page_token (alias).
list_youtube_playlist_videos(playlist_id, ...) -> dict
- Paginated.
- Returns nextPageToken and next_page_token (alias).
search_youtube_channel_videos(channel_ref, query, ...) -> dict
- Keyword search within a channel (quota-expensive, uses Search API).
- Paginated.
list_youtube_video_comments(video_id, ...) -> dict
- Public comment threads for a video (comments may be disabled).
- Paginated.

All tools except get_yt_video_info return structured JSON and are documented with AI-friendly docstrings.

Installation & MCP configuration

PyPI distribution name: glonorce-youtube-mcp
Repo name: youtube_mcp · import name: youtube_mcp

API key

All inventory/search/comment tools require a YouTube Data API v3 key:

YOUTUBE_API_KEY

Option 1 (recommended for MCP hosts): pipx (no repo clone)

Use this when you want a "zero local project" setup (no clone, no venv management).

{
  "mcpServers": {
    "youtube_mcp": {
      "command": "pipx",
      "args": ["run", "--spec", "glonorce-youtube-mcp", "youtube_mcp"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Option 2: pip into a dedicated venv (no repo clone)

python -m venv .venv_youtube_mcp
# Windows: .venv_youtube_mcp\Scripts\activate
# macOS/Linux: source .venv_youtube_mcp/bin/activate

python -m pip install -U pip
python -m pip install glonorce-youtube-mcp

MCP host JSON example (simple):

{
  "mcpServers": {
    "youtube_mcp": {
      "command": "youtube_mcp",
      "env": {
        "YOUTUBE_API_KEY": "YOUR_KEY"
      }
    }
  }
}

If your MCP host can't find youtube_mcp on PATH (Windows error like: executable file not found in %PATH%), use an absolute path.

MCP host JSON example (absolute path to venv Python + module):

{
  "mcpServers": {
    "youtube_mcp": {
      "command": "C:\\PATH\\.venv_youtube_mcp\\Scripts\\python.exe",
      "args": ["-m", "youtube_mcp.server"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Option 3: local clone (development)

git clone https://github.com/glonorce/youtube_mcp.git
cd youtube_mcp

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate

python -m pip install -e .

MCP host JSON example (local clone):

{
  "mcpServers": {
    "youtube_mcp": {
      "command": "C:\\PATH\\youtube_mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "youtube_mcp.server"],
      "env": {
        "YOUTUBE_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Getting Your YouTube API Key

While not required, you can optionally set up a YouTube Data API key for enhanced functionality. Here's how to get one:

Step 1: Create a Google Cloud Project

Go to the Google Cloud Console
Click "Select a project" at the top of the page
Click "New Project" and give it a name (e.g., "MCP YouTube Extract")
Click "Create"

Step 2: Enable the YouTube Data API

In your new project, go to the API Library
Search for "YouTube Data API v3"
Click on it and then click "Enable"

Step 3: Create API Credentials

Go to the Credentials page
Click "Create Credentials" and select "API Key"
Your new API key will be displayed - copy it immediately
Click "Restrict Key" to secure it (recommended)

Step 4: Restrict Your API Key (Recommended)

In the API key settings, click "Restrict Key"
Under "API restrictions", select "Restrict key"
Choose "YouTube Data API v3" from the dropdown
Click "Save"

Step 5: Set Up Billing (May be required)

Go to the Billing page
Link a billing account to your project
Note: YouTube Data API has a free tier of ~10,000 units per day, which is typically sufficient for most use cases

API Key Usage Limits

Free Tier: ~10,000 units per day (commonly)
Cost: depends on your Google Cloud / billing configuration

Security Best Practices

Never commit your API key to version control
Use environment variables as shown in the MCP configuration section
Restrict your API key to only the YouTube Data API
Monitor usage in the Google Cloud Console

Example MCP calls (JSON payloads)

Exact envelope depends on your MCP client; these show tool + arguments.

Resolve a channel

{
  "tool": "resolve_youtube_channel",
  "arguments": {
    "channel_ref": "@GoogleDevelopers",
    "resolution_mode": "strict",
    "include_uploads_playlist": true
  }
}

List channel videos (safe default)

{
  "tool": "list_youtube_channel_videos",
  "arguments": {
    "channel_ref": "@GoogleDevelopers",
    "max_videos": 50,
    "page_token": null,
    "include_shorts": false,
    "include_live": false,
    "parts_level": "basic",
    "order_strategy": "uploads_playlist",
    "order_by": "date"
  }
}

Quota reference (best-effort)

This section is a best-effort summary and may change over time. Always verify with official documentation.

Last verified: 2026-02-18

Official references:

YouTube Data API quota calculator / costs: https://developers.google.com/youtube/v3/determine_quota_cost
Usage limits: https://developers.google.com/youtube/v3/getting-started#quota

Approximate quota usage by tool

Note: get_yt_video_info returns text (not structured JSON) and is not included in the quota table because its behavior depends on optional extractors.

Tool	Primary endpoints	Typical cost (rough)	Notes
`resolve_youtube_channel`	`channels.list`	~1	strict mode mostly `channels.list`; best_effort may use `search.list`
`list_youtube_channel_videos` (default)	`channels.list` + `playlistItems.list` + `videos.list`	~ (1 + 1 + 1) per page	uploads-playlist strategy
`list_youtube_channel_videos` (`order_strategy=search_api`)	`search.list` + `videos.list`	~ (100 + 1) per page	expensive; capped behavior
`list_youtube_channel_playlists`	`playlists.list`	~1 per page	public playlists only
`list_youtube_playlist_videos`	`playlistItems.list` + `videos.list`	~ (1 + 1) per page	public playlist
`search_youtube_channel_videos`	`search.list` + `videos.list`	~ (100 + 1) per page	keyword search within a channel
`list_youtube_video_comments`	`commentThreads.list`	~1 per page	comments may be disabled (403)

Daily quota:

Common free quota: 10,000 units/day
Reset: daily (Google-defined; see official docs/console)

Testing

Use the venv interpreter to avoid accidentally running global pytest.

# recommended
python -m pytest -q

# if you use a venv
.venv\Scripts\python.exe -m pytest -q

Troubleshooting

Only `get_yt_video_info` is visible (other tools missing)

Your MCP host is running an old installed copy from site-packages. Fix:

python -m pip install -e .

Then restart the MCP host.

`YOUTUBE_API_KEY` placeholder is not expanded in some MCP hosts

Some MCP hosts do not interpolate placeholders like ${YOUTUBE_API_KEY} inside mcp.json.

❌ Not recommended (may be taken literally):

{
  "env": { "YOUTUBE_API_KEY": "${YOUTUBE_API_KEY}" }
}

✅ Recommended (explicit value in config):

{
  "env": { "YOUTUBE_API_KEY": "YOUR_REAL_KEY_HERE" }
}

✅ Also works (set it in the host process environment, then reference nothing in JSON):

set YOUTUBE_API_KEY in the MCP host environment (OS/IDE)
then keep mcp.json without placeholders

License

MIT — see LICENSE

Acknowledgements

This project was originally derived from / inspired by https://github.com/sinjab/mcp_youtube_extract. The codebase has since been heavily rewritten and extended.

Available Tools

7 tools

get_yt_video_infoA

Fetch YouTube video information and transcript.

Tip: You can pass either a raw video id (11 chars) or a full YouTube URL.

ParametersJSON Schema

Name	Required	Description	Default
`video_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description lacks disclosure of behavioral traits such as read-only nature, authentication requirements, or rate limits. Only adds tip about input format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no redundancy. First sentence states purpose, second provides a helpful tip. Efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists reducing need for return description. However, given lack of behavioral transparency and no annotations, the description minimally covers context for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds significant meaning by explaining the video_id parameter can be a raw ID or full URL, going beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Fetch YouTube video information and transcript' with a specific verb and resource. Distinguished from sibling tools which focus on listing playlists or channel videos.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tip explicitly allows passing raw video ID or full URL, providing clear usage context. No explicit when-not or alternatives but usage is straightforward given sibling tool purposes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_youtube_channel_playlistsA

List public playlists for a channel.

Parameters: channel_ref: Same formats as resolve_youtube_channel. page_token: Token for pagination.

Returns: - items: playlist[] (YouTube API playlist resources) - nextPageToken: string | null - quotaEstimate: {estimatedUnits,strategy,notes[]}

Notes: - Public playlists only. - This tool does not list "private" playlists.

ParametersJSON Schema

Name	Required	Description	Default
`page_token`	No
`channel_ref`	Yes
`next_page_token`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It clearly states it only accesses public playlists, which is a key behavioral trait. The inclusion of quota estimates in the return also adds transparency. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections for parameters, returns, and notes. The first sentence front-loads the purpose. It is concise without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's scope (public playlists only), pagination, and return structure. Since an output schema exists, it is not required to detail every field. The mention of quota estimates adds useful context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It describes channel_ref's format by referencing resolve_youtube_channel and mentions page_token for pagination. However, next_page_token is present in the schema but not described.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists public playlists for a channel, with a specific verb ('list') and resource ('playlists'). It distinguishes from siblings like list_youtube_channel_videos by focusing on playlists.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions the tool lists only public playlists and explicitly notes it does not list private playlists, providing a clear usage constraint. However, it does not direct the agent to alternative tools for private playlists or other scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_youtube_channel_videosA

List videos for a channel (public data), with safe defaults.

Default behavior (safe + complete): - Uses the channel's uploads playlist (uploadsPlaylistId) to paginate through all uploaded videos.

Parameters: channel_ref: Same formats as resolve_youtube_channel. max_videos: Hard limit per tool call. The tool may return fewer items and set truncated=true. page_token: Token for pagination (from previous response nextPageToken). Alias: you may also pass next_page_token (some agents prefer it). include_shorts: Default false. If true, includes Shorts (best-effort classification). include_live: Default false. If true, includes live/upcoming videos (best-effort). parts_level: - basic (default): snippet + statistics + contentDetails - full: also requests status/liveStreamingDetails (heavier payload) order_strategy: - uploads_playlist (default): low quota, paginated. - local_sort: fetches a bounded subset then sorts locally. (Not paginated; page_token must be null.) - search_api: uses YouTube Search API ordering (expensive, capped). Explicit opt-in only. order_by: - date (default) - viewCount, likeCount, commentCount, duration Note: search_api supports only date and viewCount.

Returns (structured JSON): - items: video[] (YouTube API video resources) - nextPageToken: string | null - next_page_token: string | null (alias of nextPageToken for agent friendliness) - quotaEstimate: {estimatedUnits,strategy,notes[]} - truncated: bool - appliedMaxVideos: int - appliedOrder: {strategy, by}

Quota/performance notes: - Search API calls are expensive (quota ~100/unit per call) and may be capped for channels. - local_sort is bounded by max_videos and max_pages.

Safety notes: - Public data only; no private playlists/videos. - No file/network access except YouTube Data API endpoints.

ParametersJSON Schema

Name	Required	Default
`order_by`	No	date
`max_videos`	No
`page_token`	No
`channel_ref`	Yes
`parts_level`	No	basic
`include_live`	No
`include_shorts`	No
`order_strategy`	No	uploads_playlist
`next_page_token`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully bears the burden. It discloses public-only data, safe defaults, quota estimates, pagination, truncation, and safety notes (no file/network access). Behavior is transparent and complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (default behavior, parameters, returns, notes). It is lengthy but every sentence adds value. Slightly verbose, but appropriate for complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters, no annotations, and an output schema, the description is thorough. It covers all parameters, behavior, quotas, safety, and return structure. No gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining each parameter in detail: channel_ref formats, max_videos as hard limit, page_token alias, include_shorts/live defaults, parts_level options, order_strategy/order_by options and constraints. It also explains return fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List videos for a channel (public data), with safe defaults.' The name and title align perfectly. It differentiates from siblings like list_youtube_playlist_videos by focusing on channel videos.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides extensive usage guidance: default behavior, pagination, parameter explanations, and when to use different order strategies (e.g., 'Explicit opt-in only' for search_api). However, it does not explicitly contrast with sibling tools (e.g., when to use list_youtube_playlist_videos instead).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_youtube_playlist_videosA

List videos in a playlist (public data).

Parameters: playlist_id: YouTube playlist ID (e.g. PL...). page_token: Token for pagination. max_items: Max number of items to include from this page. include_shorts/include_live: Default false; best-effort classification. parts_level: basic/full (same meaning as channel videos).

Returns: - items: video[] - nextPageToken: string | null - quotaEstimate: {estimatedUnits,strategy,notes[]}

Notes: - Playlist ordering is YouTube's playlist ordering.

ParametersJSON Schema

Name	Required	Default
`max_items`	No
`page_token`	No
`parts_level`	No	basic
`playlist_id`	Yes
`include_live`	No
`include_shorts`	No
`next_page_token`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. States 'public data' implying read-only. Mentions 'best-effort classification' for include_shorts/include_live. Returns include quotaEstimate, providing usage cost awareness. However, does not mention authentication requirements or rate limits, which would be helpful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with separate sections for description, parameters, returns, and notes. Uses bullet points for clarity. Every sentence adds value. Front-loaded with purpose statement. No unnecessary text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters, no annotations, and sibling tools, description covers most needed information. Explains returns (items, nextPageToken, quotaEstimate). But misses describing next_page_token parameter and does not reference sibling tools for context. Adequate but could be more comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description adds significant meaning. Explains playlist_id, page_token (pagination), max_items, include_shorts/include_live (default false, best-effort), and parts_level (basic/full). However, input schema also includes next_page_token parameter which is not described, causing potential confusion.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description starts with 'List videos in a playlist' which clearly states verb and resource. Adds 'public data' to clarify scope. Distinguishes from siblings like list_youtube_channel_videos (which lists videos from a channel) and list_youtube_channel_playlists (which lists playlists of a channel).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. Does not mention when not to use it or reference sibling tools for comparison. The description only states what it does, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_youtube_video_commentsA

List comment threads for a YouTube video (public comments).

Notes: - Uses commentThreads.list (quota cost ~1 per page). - max_threads is capped to 100 by the API.

Pagination: - Response returns nextPageToken and next_page_token. - Pass it back as page_token (or next_page_token) to fetch the next page.

Returns: - items: commentThread[] (includes top-level comment; replies optional) - nextPageToken / next_page_token - quotaEstimate

Common failure: - If comments are disabled, YouTube may return 403 (commentsDisabled).

ParametersJSON Schema

Name	Required	Default
`order`	No	relevance
`video_id`	Yes
`page_token`	No
`max_threads`	No
`text_format`	No	plainText
`include_replies`	No
`next_page_token`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses API method, quota cost, pagination mechanism, max cap, and a common failure. This is comprehensive for a read-only list tool, though it could explicitly state read-only nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with a main line, notes, pagination, returns, and common failure. Each section is short and to the point, with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters and no schema descriptions or annotations, the description covers purpose, behavior, outputs, and failure. Output schema exists, so detailed return fields are not needed. Missing some param details and usage guidelines, but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains pagination tokens, max_threads cap, and order default, but does not describe video_id, text_format, or include_replies beyond implicit hints. The output description partially fills gaps but not completely.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List comment threads for a YouTube video (public comments),' specifying the verb, resource, and context. This distinguishes it from sibling tools that focus on videos, playlists, or channels.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides basic context (listing comments) and mentions a failure case (403 if disabled). However, it does not explicitly state when to use this tool versus alternatives or when not to use it. With no sibling comment tools, the need for guidance is lower, but still room for improvement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_youtube_channelA

Resolve a YouTube channel reference into a concrete channelId.

What this tool does: - Converts a user-facing channel identifier into a YouTube channelId. - Optionally returns the channel's uploadsPlaylistId, which enables listing all uploaded videos via playlistItems.list.

Supported input formats (examples): - Handle: @GoogleDevelopers - Handle URL: https://www.youtube.com/@GoogleDevelopers - Channel ID URL: https://www.youtube.com/channel/UC... - Legacy username URL: https://www.youtube.com/user/SomeUsername

Parameters: channel_ref: Channel identifier in one of the supported formats. resolution_mode: - strict (default): ambiguous inputs are rejected with an explainable error. This prevents "silent wrong channel" bugs. - best_effort: ambiguous inputs return a short list of candidate channels. (This mode may use the Search API and can be expensive.) include_uploads_playlist: If true, attempts to include uploadsPlaylistId in the output.

Returns (structured JSON): - channelId: string | null - title: string | null - handle: string | null - uploadsPlaylistId: string | null - warnings: string[] - candidates: {channelId,title,handle}[]

Failure modes: - Missing API key: raises error "YOUTUBE_API_KEY not configured". - Ambiguous/unsupported input (strict): raises ValueError with guidance.

Safety notes: - Does not perform destructive actions. - Does not access private channel data.

ParametersJSON Schema

Name	Required	Default
`channel_ref`	Yes
`resolution_mode`	No	strict
`include_uploads_playlist`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explicitly states safety notes: no destructive actions, no access to private channel data. It also details failure modes (missing API key, ambiguous input) and behavior of resolution modes. This fully informs the agent of the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (What this tool does, Supported input formats, Parameters, Returns, Failure modes, Safety notes). It is comprehensive but not overly verbose. The main purpose is front-loaded. Minor redundancy could be trimmed, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, output schema exists), the description is complete. It covers input formats, parameter behavior, return structure (structured JSON), failure modes, and safety. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% description coverage, but the description explains each parameter in detail: channel_ref formats, resolution_mode options (strict vs best_effort) with implications, and include_uploads_playlist boolean. This adds significant meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Resolve a YouTube channel reference into a concrete channelId.' It specifies the verb (resolve) and resource (YouTube channel reference to channelId). It also lists supported input formats, making the scope explicit. The tool is distinct from siblings like get_yt_video_info or list_youtube_channel_playlists, which handle different tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains that the tool converts user-facing channel identifiers into channelId, and optionally provides uploadsPlaylistId. It implies usage when you have a channel reference, but does not explicitly state when not to use it or mention alternatives, though the sibling tools suggest other cases. Clear context but no exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_youtube_channel_videosA

Search for videos within a channel by keyword (public data).

When to use: Use this tool when you want to find videos by keyword without enumerating the full uploads playlist.

Important: - This tool uses the YouTube Search API (search.list). - Search is quota-expensive (about 100 units per page). - Results may be capped by YouTube API behavior for channel searches.

Pagination: - Read nextPageToken (or next_page_token) from the response. - Pass it back as page_token (or next_page_token) to fetch the next page.

Returns: - items: hydrated video resources (videos.list) - nextPageToken / next_page_token - quotaEstimate

ParametersJSON Schema

Name	Required	Default
`order`	No	relevance
`query`	Yes
`max_videos`	No
`page_token`	No
`channel_ref`	Yes
`parts_level`	No	basic
`include_live`	No
`include_shorts`	No
`next_page_token`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that it uses the YouTube Search API, is quota-expensive (100 units per page), and results may be capped. Also explains pagination mechanism with page_token, adding value beyond no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections (purpose, when to use, important notes, pagination, returns). Each sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Provides sufficient context for most aspects: purpose, usage, pagination, and return values. However, lacks parameter explanations for non-obvious fields, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It explains pagination tokens but does not describe other parameters like order, max_videos, parts_level, etc., leaving gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches for videos within a channel by keyword, distinguishing it from sibling tools like list_youtube_channel_videos which enumerates the full playlist.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Includes a 'When to use' section explicitly recommending this tool for keyword searches without enumerating the full uploads playlist, providing clear context for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv2.0.0Feb 19, 2026
- First observedget_yt_video_info
- First observedlist_youtube_channel_playlists
- First observedlist_youtube_channel_videos
- First observedlist_youtube_playlist_videos
- First observedlist_youtube_video_comments
- First observedresolve_youtube_channel
- First observedsearch_youtube_channel_videos

Deploy Server

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

TDQS

A4.2/5.0

Scored 2026-06-04 10:35 across 7 tools

Disambiguation5/5

Each tool targets a distinct resource or operation: video info, channel playlists, channel videos, playlist videos, video comments, channel resolution, and keyword search. While list_youtube_channel_videos and search_youtube_channel_videos both deal with channel videos, one is for listing all uploads and the other for keyword search, making them clearly separable.

Naming Consistency4/5

Most tools follow a 'verb_youtube_noun' pattern (e.g., list_youtube_channel_playlists, list_youtube_video_comments). However, 'get_yt_video_info' uses the abbreviation 'yt' instead of 'youtube', breaking the pattern. This is a minor inconsistency.

Tool Count5/5

With 7 tools covering core read operations for YouTube data, the count feels well-scoped. Each tool earns its place, providing a focused but sufficient interface for common tasks like fetching video info, listing playlists/videos, retrieving comments, resolving channels, and searching.

Completeness4/5

The tool set covers the main read operations: video info, channel playlists, channel videos, playlist videos, video comments, channel resolution, and keyword search. Missing are direct playlist metadata retrieval and detailed channel statistics, but for a read-only interface these are minor gaps.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

BulkTranscripts YouTube AOAuth
co.bulktranscripts
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Entertainment & Media
101
YouTube Transcript & Search MCP Server A
com.transcriptout
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
Entertainment & Media Search
141
YouTube Transcript + YouTube Search MCP AOAuth
com.getyoutubetranscript
YouTube transcripts, search, channel browsing, and playlists for AI agents via MCP.
Entertainment & Media Search Web Scraping
61
ScriptHaul API
com.scripthaul
YouTube discovery, transcripts, library search, and monitors with API keys or OAuth.
Entertainment & Media Search
1

Related MCP Servers

YouTube Knowledge MCP
Search Knowledge & Memory RAG Systems
efikuta
A
license
B
quality
D
maintenance
Transforms YouTube into a queryable knowledge source with search, video details, transcript analysis, and AI-powered tools for summaries, learning paths, and knowledge graphs. Features quota-aware API access with caching and optional OpenAI/Anthropic integration for advanced content analysis.
Updated a year ago (2025-10-21 11:05 UTC)
10
211 npm
1
MIT
YouTube MCP Server
Entertainment & Media Search Content Management Systems
sfiorini
A
license
A
quality
C
maintenance
Enables AI models to interact with YouTube content including video details, transcripts, channel information, playlists, and search functionality through the YouTube Data API.
Updated 10 months ago (2025-11-22 04:51 UTC)
7
14 npm
10
MIT
mcp-server-youtube
Entertainment & Media Search
vaporif
A
license
Not graded
quality
C
maintenance
Enables AI assistants to search videos, read channels, browse playlists, fetch comments, and get transcripts from YouTube using the YouTube Data API v3 and InnerTube API for captions.
Updated 6 months ago (2026-03-21 09:44 UTC)
2
GPL 3.0
youtube-connector-mcp
Entertainment & Media Search Social Media
ShellyDeng08
A
license
Not graded
quality
C
maintenance
Enables AI assistants to search videos, channels, and playlists, retrieve video metadata, transcripts, and comments via the YouTube Data API v3.
Updated 6 months ago (2026-03-19 02:34 UTC)
71
MIT

Appeared in Searches

A server for finding channels

YouTube MCP (youtube_mcp)

Prerequisites (PATH)

✨ Available on PyPI

Screenshots

Features

Tools

Installation & MCP configuration

API key

Option 1 (recommended for MCP hosts): pipx (no repo clone)

Option 2: pip into a dedicated venv (no repo clone)

Option 3: local clone (development)

Getting Your YouTube API Key

Step 1: Create a Google Cloud Project

Step 2: Enable the YouTube Data API

Step 3: Create API Credentials

Step 4: Restrict Your API Key (Recommended)

Step 5: Set Up Billing (May be required)

API Key Usage Limits

Security Best Practices

Example MCP calls (JSON payloads)

Resolve a channel

List channel videos (safe default)

Quota reference (best-effort)

Approximate quota usage by tool

Testing

Troubleshooting

Only get_yt_video_info is visible (other tools missing)

YOUTUBE_API_KEY placeholder is not expanded in some MCP hosts

License

Acknowledgements

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Only `get_yt_video_info` is visible (other tools missing)

`YOUTUBE_API_KEY` placeholder is not expanded in some MCP hosts