使用说明

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客户端连接。

生产部署（渲染）

一键部署：

手动部署：

分叉此存储库
在渲染时创建新的Web服务：
- 首选渲染仪表板
- 点击“新建+”→ “Web服务”
- 连接您的GitHub存储库

配置服务：

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

设置环境变量（可选）：
```
FASTMCP_LOG_LEVEL=INFO
```
部署 -Render将自动使用HTTPS部署您的MCP服务器

您的服务器将在以下位置可用： https://ytmcp-<random>.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

🧠 设计原则

速率限制优先 -全局0.75s延迟防止IP禁令
图书馆专业：
- scrapetube → 快速频道/播放列表列表
- youtube-search-python → 搜索和筛选
- yt-dlp → 全面的元数据提取
- youtube-transcript-api → 获取成绩单
LLM优化输出 -Markdown中的所有回复
双模式操作 -STDIO用于本地，HTTPS用于生产
健康监测 - /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"]
    }
  }
}

环境变量

变量	默认值	描述
`FASTMCP_LOG_LEVEL`	`INFO`	日志记录级别(`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`FASTMCP_HOST`	`127.0.0.1`	要绑定的主机（HTTP传输）
`FASTMCP_PORT`	`8000`	要绑定的端口（HTTP传输）
`PORT`	-	渲染自动指定此（生产）

📚 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集成用于自动部署

步骤：

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

健康检查： 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

铁路

连接GitHub仓库
添加环境变量
使用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）

🤝 贡献

欢迎投稿！拜托：

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

开发工作流程：

# 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 -协议基础

📞 支持

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

建于❤️ LLM生态系统