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
安装:```bash
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 .
**运行服务器:**```bash
# Using UV
uv run ytmcp
# OR using pip
ytmcp
服务器将以STDIO模式启动,准备接受MCP客户端连接。
生产部署(渲染)
一键部署:
手动部署:
-
分叉此存储库
-
在渲染时创建新的Web服务:
- 首选 渲染仪表板
- 点击“新建+”→ “Web服务”
- 连接您的GitHub存储库
- 配置服务:```yaml
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
- 部署 -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禁令
1. **图书馆专业:**
- `scrapetube` → 快速频道/播放列表列表
- `youtube-search-python` → 搜索和筛选
- `yt-dlp` → 全面的元数据提取
- `youtube-transcript-api` → 获取成绩单
1. **LLM优化输出** -Markdown中的所有回复
1. **双模式操作** -STDIO用于本地,HTTPS用于生产
1. **健康监测** - `/health` 负载平衡器的端点
______________________________________________________________________
## ⚙️ 配置
### MCP客户端
#### **Gemini CLI** (`.gemini/mcp_config.json`)```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)```json
{
"mcpServers": {
"ytmcp": {
"command": "uv",
"args": ["--directory", "/path/to/ytmcp", "run", "ytmcp"]
}
}
}
#### **光标** (`.cursor/mcp.json`)```json
{
"mcpServers": {
"ytmcp": {
"command": "uv",
"args": ["--directory", "/path/to/ytmcp", "run", "ytmcp"]
}
}
}
VS代码继续 (~/.continue/config.json)```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参考
### 工具调用示例
#### 搜索视频```python
search_videos_tool(
query="python tutorial",
limit=10
)
退货: Markdown格式的列表,包括标题、频道、视图、网址
获取视频转录```python
get_transcript_tool(
video_id="dQw4w9WgXcQ", # Or full URL
languages="en,de" # Fallback languages
)
**退货:** 与时间同步的成绩单 `[MM:SS]` 时间戳
______________________________________________________________________
#### 分析渠道```python
get_channel_videos_tool(
channel_id="@fireship", # Supports @handle, ID, or URL
sort_by="popular",
limit=20
)
退货: 带元数据的排序视频列表
提取元数据```python
get_video_metadata_tool(
video_id="https://youtube.com/watch?v=dQw4w9WgXcQ"
)
**退货:** 全面的元数据(视图、点赞、描述、标签等)
______________________________________________________________________
## 🛠️ 发展
### 设置开发环境```bash
# Install with dev dependencies
uv sync --dev
# Run tests
uv run pytest
# Type checking
uv run mypy src/
# Linting
uv run ruff check src/
运行不同的运输工具```bash
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
### 代码结构
每个工具都遵循以下模式:```python
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```bash
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仓库
1. 添加环境变量
1. 使用Procfile进行部署
______________________________________________________________________
### Docker(自托管)```dockerfile
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"]
``````bash
docker build -t ytmcp .
docker run -p 8080:8080 ytmcp
🔒 安全与合规
- 只读: 没有对YouTube的写入操作
- 没有API密钥: 使用抓取库(查看YouTube ToS以了解商业用途)
- 隐私: 无用户身份验证或跟踪
- 速率限制: 防止滥用和IP禁令
- 运输安全: HTTPS在生产中,SSH用于STDIO
⚠️ YouTube服务条款:
此服务器使用绕过YouTube API官方配额的抓取库。审查 YouTube的ToS 在部署用于商业目的之前。
🐛 故障排除
服务器无法启动
检查Python版本:```bash
python --version # Should be 3.13+
**重新安装依赖关系:**```bash
uv sync --reinstall
速率限制过于激进
调整 src/ytmcp/middleware/rate_limiter.py:```python
rate_limiter = RateLimiter(delay_seconds=0.5) # Faster (risky)
______________________________________________________________________
### 渲染部署失败
**检查构建日志:**
- 确保Python 3.13可用
- 验证 `runtime.txt` 指定 `python-3.13`
**常见修复:**```yaml
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格式化输出
- 更新文档
开发工作流程:```bash
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生态系统