youtube-mcp-server

一个远程 MCP 服务器，通过 Streamable HTTP 将 YouTube Data API v3 以工具的形式暴露出来，因此可以将其作为自定义连接器添加到 claude.ai。

无依赖。无需构建步骤。node src/server.js 就是全部。

工具

字幕功能是刻意不实现的。captions.download 需要 OAuth 以及对视频的编辑权限，因此 API 密钥只能获取你自己视频的字幕。据广泛报道，非官方的爬取库会被云 IP 段屏蔽，而本服务器恰恰就运行在这些云 IP 段上。

Related MCP server: mcp-server-youtube

配额

一个项目每天在通用配额池中获得 10,000 个配额单位，而 search.list 位于独立的配额池中，上限为每天 100 次调用。这一点决定了工具的设计：youtube_channel_videos 走 channels.list → playlistItems.list → videos.list，而不是 search.list?channelId=，因此浏览一个频道花费 3 个通用配额单位，而不是用掉每天仅有的 100 次搜索中的一次。

本地运行

cp .env.example .env        # add your YOUTUBE_API_KEY
export $(grep -v '^#' .env | xargs)
npm start

curl localhost:3000/health

curl -s localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

测试

npm test

针对模拟的 YouTube API 运行完整的 MCP 握手、两种传输模式、全部五个工具以及错误路径。无需 API 密钥，也无需网络。

部署到 Railway

1. 将此仓库推送到 GitHub。

2. Railway → 新建项目 → 从 GitHub 仓库部署 → 选择它。

3. 变量 → 添加 YOUTUBE_API_KEY。

4. 设置 → 网络 → 生成域名。

5. 检查 https://<your-domain>/health 是否返回 "apiKeyConfigured": true。

Railway 会自动设置 PORT；服务器绑定 0.0.0.0 并读取该变量。

添加到 claude.ai

自定义 → 连接器 → 添加自定义连接器 → https://<your-domain>/mcp

无需 OAuth 字段——服务器默认无需认证。若要锁定访问，请设置 MCP_AUTH_TOKEN，并在连接器请求标头的 authorization 中填入 Bearer <token>。

环境变量

设计说明

无状态。每个 POST 请求都是自包含的——没有 Mcp-Session-Id，没有会话映射——因此重启或增加第二个副本绝不会产生 "No valid session ID provided" 错误。

内容协商与参考 SDK 一致：当客户端发送 Accept: text/event-stream 时返回 SSE 帧，否则返回纯 JSON 主体。

对 /mcp 的 GET 和 DELETE 请求返回 405，这正符合 Streamable HTTP 规范对没有服务器发起的流、也没有会话需要关闭的服务器的预期。

不验证 Origin 标头，也没有 DNS 重绑定保护。这些防御措施是为绑定到 localhost 的 MCP 服务器设计的；若在公共部署中保留，它们会拒绝 Anthropic 自己的请求，这是 initialize 超时的常见原因。

工具失败会以 isError: true 内容的形式返回，而不是 JSON-RPC 错误，因此 Claude 能读取到出错原因并做出调整，而不是让调用在传输层直接失败。

结果会被截断到 120k 字符，低于 claude.ai 的 ~150k 工具结果上限。