YouTube数据协议服务

YouTube MCP（YouTube_MCP）

A. 模型上下文协议（MCP） 提供以下功能的服务器 生产级YouTube库存工具 （频道分辨率、频道视频、频道播放列表、播放列表视频）旨在 默认安全，配额意识，人工智能友好。

存储库：https://github.com/glonorce/youtube_mcp PyPI：https://pypi.org/project/glonorce-youtube-mcp/

命名说明：

• 回购名称： youtube_mcp
• Python包/导入名称： youtube_mcp
• MCP入口模块： python -m youtube_mcp.server

先决条件（PATH）

确保这些命令在您的终端中工作（它们必须打开 PATH):

• python --version
• python -m pip --version
• pipx --version （仅当您使用基于pipx的MCP配置时）

where python
where pipx
$env:Path

在Windows上：

• 从以下位置安装Pythonhttps://www.python.org/downloads/
• 安装过程中，检查 “将Python添加到PATH”

安装pipx（仅当您使用基于pipx的MCP配置时）：

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

笔记：

• 之后 pipx ensurepath，重新启动终端/IDE，以便 pipx 可在 PATH.
• 通过以下方式进行验证： pipx --version

✨ 在PyPI上可用

pip install glonorce-youtube-mcp

# run
youtube_mcp

截图

特性

• 7个MCP工具 （1个文本输出工具+6个结构化输出工具）
• 安全默认值 （仅限公共数据；除非启用，否则不包括短片/直播）
• 配额意识设计 （预算+昂贵的策略作为明确的选择加入）
• 工具发现在MCP主机中工作 （使用富文档字符串注册的工具）
• 弹性YouTube数据API客户端 （端点分配列表、重试、gzip处理）

工具

此服务器公开 7工具:

1. get_yt_video_info(video_id_or_url) -> str

   • 接受原始视频id 或 完整的YouTube URL。
   • 返回视频元数据+转录（如果可用）。

2. resolve_youtube_channel(channel_ref, ...) -> dict

3. list_youtube_channel_videos(channel_ref, ...) -> dict

   • 分页。
   • 退货 nextPageToken 和 next_page_token （别名）。

4. list_youtube_channel_playlists(channel_ref, ...) -> dict

   • 分页。
   • 退货 nextPageToken 和 next_page_token （别名）。

5. list_youtube_playlist_videos(playlist_id, ...) -> dict

   • 分页。
   • 退货 nextPageToken 和 next_page_token （别名）。

6. search_youtube_channel_videos(channel_ref, query, ...) -> dict

   • 频道内的关键字搜索(配额昂贵，使用搜索API）。
   • 分页。

7. list_youtube_video_comments(video_id, ...) -> dict

   • 视频的公共评论线程（评论可能被禁用）。
   • 分页。

除以下工具外的所有工具 get_yt_video_info 返回 结构化JSON 并使用AI友好的文档字符串进行记录。

安装和MCP配置

PyPI分发名称： glonorce-youtube-mcp

回购名称： youtube_mcp ·导入名称： youtube_mcp

API密钥

所有库存/搜索/评论工具都需要YouTube Data API v3密钥：

• YOUTUBE_API_KEY

选项1（建议用于MCP主机）：pipx（无回购克隆）

当您想要“零本地项目”设置（无克隆，无venv管理）时，请使用此选项。

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

选项2：pip到专用venv（无回购克隆）

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主机JSON示例（简单）：

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

如果您的MCP主机找不到 youtube_mcp 上 PATH （Windows错误，如： executable file not found in %PATH%)，使用 绝对路径.

MCP主机JSON示例（venv Python+模块的绝对路径）：

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

选项3：本地克隆（开发）

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主机JSON示例（本地克隆）：

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

获取YouTube API密钥

虽然不是必需的，但您可以选择设置YouTube数据API密钥以增强功能。以下是如何获得一个：

第一步：创建谷歌云项目

1. 去 Google 云控制台
2. 点击页面顶部的“选择项目”
3. 点击“新建项目”并为其命名（例如，“MCP YouTube摘录”）
4. 点击“创建”

步骤2：启用YouTube数据API

1. 在您的新项目中，请转到 API库
2. 搜索“YouTube数据API v3”
3. 点击它，然后点击“启用”

步骤3：创建API凭据

1. 去 凭证页面
2. 单击“创建凭据”并选择“API密钥”
3. 将显示您的新API密钥-立即复制它
4. 点击“限制密钥”以保护它（推荐）

步骤4：限制您的API密钥（推荐）

1. 在API密钥设置中，单击“限制密钥”
2. 在“API限制”下，选择“限制密钥”
3. 从下拉列表中选择“YouTube Data API v3”
4. 点击“保存”

步骤5：设置账单（可能需要）

1. 去 账单页面
2. 将账单帐户链接到您的项目
3. 备注：YouTube Data API每天有约10000个单元的免费层，这通常足以满足大多数用例

API密钥使用限制

• 免费套餐：每天约10000单位（通常）
• 成本：取决于您的Google Cloud/计费配置

安全最佳实践

• 永远不要提交API密钥 到版本控制
• 使用环境变量 如MCP配置部分所示
• 限制API密钥 仅限于YouTube数据API
• 监控使用情况 在Google Cloud控制台中

MCP调用示例（JSON有效载荷）

确切的信封取决于您的MCP客户；这些节目 tool + arguments.

解析频道

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

列出频道视频（安全默认）

{
  "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"
  }
}

配额参考（尽最大努力）

本节为 尽最大努力 总结，并可能随时间而变化。 始终使用官方文件进行验证。

上次验证时间： 2026-02-18

官方参考：

• YouTube数据API配额计算器/成本：https://developers.google.com/youtube/v3/determine_quota_cost
• 使用限制：https://developers.google.com/youtube/v3/getting-started#quota

按工具划分的大致配额使用情况

注： get_yt_video_info 返回文本（非结构化JSON），并且不包含在配额表中，因为其行为取决于可选的提取器。

每日配额：

• 普通免费配额： 10000单位/天
• 重置：每天（谷歌定义；见官方文档/控制台）

测试

使用venv解释器避免意外运行全局 pytest.

# recommended
python -m pytest -q

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

故障排除

仅 get_yt_video_info 可见（缺少其他工具）

您的MCP主机正在运行 旧安装副本 从 site-packages. 修复：

python -m pip install -e .

然后重新启动MCP主机。

YOUTUBE_API_KEY 占位符在某些MCP主机中未展开

一些MCP主机会 不 插入占位符，如 ${YOUTUBE_API_KEY} 里面 mcp.json.

❌ 不推荐（可以按字面意思理解）：

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

✅ 推荐（配置中的显式值）：

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

✅ 同样有效（在宿主进程环境中设置它，然后在JSON中不引用任何内容）：

• 集 YOUTUBE_API_KEY 在MCP主机环境（OS/IDE）中
• 然后继续 mcp.json 没有占位符

许可证

麻省理工学院——见 许可证

致谢

这个项目最初源于/灵感来自https://github.com/sinjab/mcp_youtube_extract. 此后，代码库被大量重写和扩展。