YouTube MCP Connector for Claude.ai

生产级远程 MCP 服务器，让 Claude.ai 可以通过 HTTPS 使用只读的 YouTube 工具：

• search_videos

• get_trending_videos

• get_channel_videos

• get_video_details

• get_engagement_stats

• get_transcript

• search_transcript

该服务使用官方 YouTube Data API v3 进行搜索、元数据、热门趋势和频道上传。字幕检索采用尽力而为的策略：它首先尝试公共 InnerTube 字幕轨道，然后再尝试 YouTube 观看页面的字幕发现机制。它不会绕过 CAPTCHA、封锁或速率限制。

本地设置

npm install
cp .env.example .env

至少设置：

YOUTUBE_API_KEY=your_google_api_key
AUTH_MODE=none

本地运行：

npm run dev

健康检查：

curl http://localhost:3000/health
curl http://localhost:3000/ready

构建和测试：

npm test
npm run build

Related MCP server: youtube-research

生产环境

Railway 最低测试变量：

YOUTUBE_API_KEY=...
AUTH_MODE=none

推荐使用 Redis，但应用在没有 Redis 的情况下也可以启动，此时会使用进程内的 no-op 缓存。

完整生产变量：

NODE_ENV=production
YOUTUBE_API_KEY=...
AUTH_MODE=oauth
AUTH_ISSUER=https://YOUR_AUTH0_DOMAIN/
AUTH_AUDIENCE=https://youtube-claude-mcp
AUTH_JWKS_URL=https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json
AUTH_REQUIRED_SCOPE=youtube:read
REDIS_URL=...

默认缓存 TTL：

TRANSCRIPT_CACHE_TTL_SECONDS=604800
VIDEO_DETAILS_CACHE_TTL_SECONDS=900
TRENDING_CACHE_TTL_SECONDS=600
CHANNEL_VIDEOS_CACHE_TTL_SECONDS=600

Auth0 设置

1. 创建或复用现有的 Auth0 API。

2. 将 API 标识符设置为与 AUTH_AUDIENCE 相同的值。

3. 添加作用域 youtube:read。

4. 使用 Auth0 颁发者 URL 作为 AUTH_ISSUER。

5. 使用租户的 JWKS 端点作为 AUTH_JWKS_URL。

6. 使用相应的 Auth0 客户端详细信息，配置 Claude.ai 自定义连接器的 OAuth 高级设置。

当 AUTH_MODE=oauth 时，/mcp 端点需要有效的 Authorization: Bearer <token>。

Railway 部署

1. 将仓库推送到 GitHub。

2. 从 GitHub 仓库创建 Railway 项目。

3. Railway 应通过 railway.json 使用已提交的 Dockerfile。

4. 添加服务变量：

YOUTUBE_API_KEY=...
AUTH_MODE=none

5. 部署并打开 /health。

6. 如果以后需要共享缓存，再添加 Railway Redis，然后设置 REDIS_URL。

7. 通过设置 AUTH_MODE=oauth 和 Auth0 变量切换到 Auth0。

Render 部署

1. 创建 Render Redis 实例。

2. 从此仓库创建 Render Web Service。

3. 选择 Docker 部署。

4. 添加生产环境变量。

5. 部署。

6. 验证：

curl https://YOUR_RENDER_URL/health
curl https://YOUR_RENDER_URL/ready
curl -i https://YOUR_RENDER_URL/mcp

未经认证的 /mcp 应返回 401。

Claude.ai 连接器

1. 打开 Claude.ai 设置。

2. 转到“自定义”，然后转到“连接器”。

3. 添加自定义连接器。

4. 使用：

https://YOUR_RENDER_URL/mcp

5. 如果启用了生产环境认证，请配置 OAuth 高级设置。

6. 在聊天中启用该连接器。

演示提示词：

• 在 YouTube 上搜索 5 个最近的 MCP 服务器教程。

• 巴基斯坦现在最热门的视频是什么？

• 显示 @GoogleDevelopers 的最新视频。

• 获取这个 YouTube URL 的观看次数、点赞数和时长。

• 计算它的互动率。

• 获取字幕并总结。

• 字幕中哪里提到了认证？

运维注意事项

• 尽可能在 Google Cloud 中限制并轮换 YouTube API 密钥。

• 请勿记录 API 密钥、Bearer 令牌或完整的授权头。

• 搜索调用非常消耗配额；尽量优先使用频道上传和缓存的元数据。

• Redis 故障会降低缓存性能，但不会导致正常工具调用失败。

• 当字幕被禁用、不可用、受地域限制或被 YouTube 屏蔽时，字幕获取可能会失败。

• CAPTCHA 或机器人拦截响应会以错误形式呈现；该服务不会尝试绕过。

故障排查

• 启动失败，提示 YOUTUBE_API_KEY is required：请设置服务端 API 密钥。

• 生产环境启动失败，提示 REDIS_URL is required：请连接 Render Redis 并设置其 URL。

• /mcp 返回 401：令牌缺失、过期、格式错误，或由错误的颁发者签名。

• /mcp 返回 403：令牌有效，但缺少 youtube:read 作用域。

• 字幕工具返回不可用：该视频可能没有公开字幕。

• YouTube 配额已超出：请等待配额重置、申请提高配额，或减少搜索使用量。