Yt MCP

YtMCP-YouTube模型上下文协议服务器

YtMCP 是一个生产级模型上下文协议（MCP）服务器，通过16个专用工具提供对YouTube数据的全面、只读访问。为两者而设计 本地开发 （STDIO）和 云部署 （渲染上的HTTPS），它结合了多个经过实战考验的库，为LLM应用程序提供强大的YouTube智能。

______________________________________________________________________

📋 目录

• 特性
• 快速开始

- 地方发展（STDIO） - 生产部署（渲染）

• 工具类别
• 建筑
• 配置

- MCP客户端 - 环境变量

• api参考
• 发展
• 部署指导
• 安全与合规
• 故障排除
• 贡献
• 许可证

______________________________________________________________________

✨ 特性

🔍 A类：核心发现（5个工具）

• search_videos -具有可自定义限制的基本关键字搜索
• search_filtered -使用过滤器进行高级搜索（上传日期、持续时间、排序）
• get_trending_videos -获取当前热门视频
• find_channels -按名称或主题搜索频道
• find_playlists -按关键字查找播放列表

🎥 B类：视频智能（5工具）

• get_transcript -提取时间同步的转录本/字幕（对内容分析至关重要）
• get_video_metadata -全面的视频数据（视图、标签、描述、点赞、持续时间）
• get_video_chapters -提取视频章节/关键时刻
• get_thumbnail -高分辨率缩略图URL（所有质量）
• get_comments -获取热门评论（出于安全考虑，价格有限）

📊 C类：频道和播放列表取证（5个工具）

• get_channel_videos -按排序列出频道视频（最新、最旧、最受欢迎）
• get_channel_shorts -列出某个频道的YouTube短片
• get_channel_streams -列出直播流（过去和现在）
• get_playlist_items -精简播放列表内容
• get_channel_about -渠道描述和统计

🛠️ D类：实用工具（1个工具）

• get_audio_stream_url -获取直接音频流URL

______________________________________________________________________

🚀 快速开始

地方发展（STDIO）

先决条件：

• Python 3.13+
• UV包管理器 （推荐）或pip

安装：

# Clone the repository
git clone https://github.com/utkarshchaudhary009/ytmcp.git
cd ytmcp

# Install with UV (recommended)
uv sync

# OR install with pip
pip install -e .

运行服务器：

# Using UV
uv run ytmcp

# OR using pip
ytmcp

服务器将以STDIO模式启动，准备接受MCP客户端连接。

______________________________________________________________________

生产部署（渲染）

一键部署：

手动部署：

1. 分叉此存储库

1. 在渲染时创建新的Web服务：

- 首选 渲染仪表板 - 点击“新建+”→ “Web服务” - 连接您的GitHub存储库

1. 配置服务：

   Name: ytmcp
   Environment: Python 3
   Build Command: pip install -e .
   Start Command: ytmcp --transport streamable-http --host 0.0.0.0 --port $PORT

1. 设置环境变量（可选）：

   FASTMCP_LOG_LEVEL=INFO

1. 部署 -Render将自动使用HTTPS部署您的MCP服务器

您的服务器将在以下位置可用： https://ytmcp-.onrender.com

______________________________________________________________________

🏗️ 建筑

ytmcp/
├── src/
│   └── ytmcp/
│       ├── __init__.py
│       ├── server.py              # Main FastMCP server with health check
│       ├── middleware/
│       │   ├── __init__.py
│       │   └── rate_limiter.py    # Global rate limiting (0.75s delay)
│       └── tools/
│           ├── __init__.py
│           ├── search.py          # Category A: Search tools
│           ├── video.py           # Category B: Video intelligence
│           ├── channel.py         # Category C: Channel forensics
│           └── utils.py           # Category D: Utilities
├── examples/                      # MCP client configurations
├── research/                      # Library research & feasibility docs
├── render.yaml                    # Render deployment config
├── Procfile                       # Process definition
├── runtime.txt                    # Python version specification
├── pyproject.toml                 # Project metadata & dependencies
└── README.md

🧠 设计原则

1. 速率限制优先 -全局0.75s延迟防止IP禁令
2. 图书馆专业：

- scrapetube → 快速频道/播放列表列表 - youtube-search-python → 搜索和筛选 - yt-dlp → 全面的元数据提取 - youtube-transcript-api → 获取成绩单

1. LLM优化输出 -Markdown中的所有回复
2. 双模式操作 -STDIO用于本地，HTTPS用于生产
3. 健康监测 - /health 负载平衡器的端点

______________________________________________________________________

⚙️ 配置

MCP客户端

Gemini CLI (.gemini/mcp_config.json)

{
  "mcpServers": {
    "ytmcp-local": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ytmcp", "ytmcp"],
      "description": "YouTube MCP (Local)"
    },
    "ytmcp-prod": {
      "url": "https://your-ytmcp.onrender.com/mcp",
      "description": "YouTube MCP (Production)"
    }
  }
}

克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "ytmcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ytmcp", "run", "ytmcp"]
    }
  }
}

光标 (.cursor/mcp.json)

{
  "mcpServers": {
    "ytmcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/ytmcp", "run", "ytmcp"]
    }
  }
}

VS代码继续 (~/.continue/config.json)

{
  "mcpServers": {
    "ytmcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ytmcp", "ytmcp"]
    }
  }
}

环境变量

______________________________________________________________________

📚 api参考

工具调用示例

搜索视频

search_videos_tool(
    query="python tutorial",
    limit=10
)

退货： Markdown格式的列表，包括标题、频道、视图、网址

______________________________________________________________________

获取视频转录

get_transcript_tool(
    video_id="dQw4w9WgXcQ",  # Or full URL
    languages="en,de"         # Fallback languages
)

退货： 与时间同步的成绩单 [MM:SS] 时间戳

______________________________________________________________________

分析渠道

get_channel_videos_tool(
    channel_id="@fireship",   # Supports @handle, ID, or URL
    sort_by="popular",
    limit=20
)

退货： 带元数据的排序视频列表

______________________________________________________________________

提取元数据

get_video_metadata_tool(
    video_id="https://youtube.com/watch?v=dQw4w9WgXcQ"
)

退货： 全面的元数据（视图、点赞、描述、标签等）

______________________________________________________________________

🛠️ 发展

设置开发环境

# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

运行不同的运输工具

# STDIO (for MCP clients)
uv run ytmcp

# SSE (for web clients)
uv run ytmcp --transport sse --port 8000

# StreamableHTTP (for production)
uv run ytmcp --transport streamable-http --host 0.0.0.0 --port 8080

代码结构

每个工具都遵循以下模式：

from ..middleware.rate_limiter import rate_limiter

@rate_limiter  # Automatic rate limiting
async def tool_name(param: str) -> str:
    """Tool description."""
    # 1. Extract/validate IDs
    # 2. Define library options
    # 3. Fetch data in thread pool
    # 4. Format as Markdown
    # 5. Return LLM-optimized output

______________________________________________________________________

🚢 部署指导

渲染（推荐）

优势：

• 免费套餐，每月750小时
• 自动SSL（HTTPS）
• 崩溃时自动重启
• GitHub集成用于自动部署

步骤：

1. 将代码推送到GitHub
2. 将Render连接到您的仓库
3. 使用 render.yaml 配置（包括）
4. 部署

健康检查： https://your-app.onrender.com/health

MCP端点： https://your-app.onrender.com/mcp

______________________________________________________________________

Heroku

# Login to Heroku
heroku login

# Create app
heroku create ytmcp

# Deploy
git push heroku main

# Set environment
heroku config:set FASTMCP_LOG_LEVEL=INFO

______________________________________________________________________

铁路

1. 连接GitHub仓库
2. 添加环境变量
3. 使用Procfile进行部署

______________________________________________________________________

Docker（自托管）

FROM python:3.13-slim

WORKDIR /app
COPY . .

RUN pip install -e .

EXPOSE 8080
CMD ["ytmcp", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8080"]

docker build -t ytmcp .
docker run -p 8080:8080 ytmcp

______________________________________________________________________

🔒 安全与合规

• 只读： 没有对YouTube的写入操作
• 没有API密钥： 使用抓取库（查看YouTube ToS以了解商业用途）
• 隐私： 无用户身份验证或跟踪
• 速率限制： 防止滥用和IP禁令
• 运输安全： HTTPS在生产中，SSH用于STDIO

⚠️ YouTube服务条款： 此服务器使用绕过YouTube API官方配额的抓取库。审查 YouTube的ToS 在部署用于商业目的之前。

______________________________________________________________________

🐛 故障排除

服务器无法启动

检查Python版本：

python --version  # Should be 3.13+

重新安装依赖关系：

uv sync --reinstall

______________________________________________________________________

速率限制过于激进

调整 src/ytmcp/middleware/rate_limiter.py:

rate_limiter = RateLimiter(delay_seconds=0.5)  # Faster (risky)

______________________________________________________________________

渲染部署失败

检查构建日志：

• 确保Python 3.13可用
• 验证 runtime.txt 指定 python-3.13

常见修复：

buildCommand: pip install --upgrade pip && pip install -e .

______________________________________________________________________

MCP客户端无法连接

本地（STDIO）：

• 确保服务器正在运行： uv run ytmcp
• 检查客户端配置路径是否为绝对路径
• 重新启动MCP客户端

生产（HTTPS）：

• 验证服务器运行状况： curl https://your-app.onrender.com/health
• 检查MCP端点： https://your-app.onrender.com/mcp
• 确保HTTPS（不是HTTP）

______________________________________________________________________

🤝 贡献

欢迎投稿！拜托：

1. 审查 /research 图书馆能力
2. 遵循现有的工具模式
3. 保持限速
4. 用Markdown格式化输出
5. 更新文档

开发工作流程：

# Fork and clone
git clone https://github.com/utkarshchaudhary009/ytmcp.git

# Create feature branch
git checkout -b feature/new-tool

# Make changes and test
uv run ytmcp

# Submit PR

______________________________________________________________________

📄 许可证

MIT许可证-请参阅 许可证 文件

______________________________________________________________________

🙏 致谢

使用这些优秀的库构建：

• yt-dlp -视频元数据提取
• 刮管 -频道抓取
• youtube搜索python -搜索
• youtube转录api -成绩单
• MCP Python SDK -协议基础

______________________________________________________________________

📞 支持

• 问题：
• 讨论：
• 文档： 看 /research 用于设计决策

______________________________________________________________________

建于❤️ LLM生态系统