YouTube信息MCP服务器
](https://www.npmjs.com/package/@limecooler/yt-info-mcp)  ](https://nodejs.org) ](https://www.npmjs.com/package/@limecooler/yt-info-mcp)
一个轻量级的MCP服务器，通过web抓取提取YouTube视频元数据和转录本，具有强大的错误处理、缓存和重试逻辑，无需API密钥或外部依赖性。
目录
🚀 快速开始
npx @limecooler/yt-info-mcp就是这样！无需安装。
先决条件
- Node.js：18.0.0或更高版本
- npm：9.0.0或更高版本（用于全局安装）
- 操作系统：Windows、macOS或Linux
特性
- 获取视频元数据（标题、作者、持续时间、视图、描述）
- 下载可用的成绩单/字幕
- 不需要API密钥
- 无外部依赖（如yt-dlp）
- Claude Desktop集成的快速启动时间
- 具有特定错误代码的全面错误处理
- 使用Zod模式进行输入验证
- 具有指数回退的重试逻辑，以实现网络弹性
- 内存缓存以提高性能
- 调试日志支持（设置
MCP_DEBUG=true) - 具有完全类型安全的TypeScript
运作原理
此MCP服务器使用YouTube的InnerTube API（与YouTube移动应用程序使用的API相同）可靠地获取视频数据：
- 页面提取：检索YouTube视频页面HTML
- API密钥提取：提取
INNERTUBE_API_KEY从页面源 - InnerTube请求：向发出经过身份验证的POST请求
/youtubei/v1/player - Android环境：使用Android客户端上下文(
clientName: "ANDROID")为了更好地获取成绩单 - 回退策略：如果InnerTube失败，则返回HTML抓取
这种方法比直接获取字幕URL更可靠，因为它模仿了YouTube官方应用程序检索数据的方式。
与备选方案的比较
| 功能 | yt-info-mcp | yt-dlp | youtube-dl | youtube API |
|---|---|---|---|---|
| 不需要API密钥 | ✅ | ✅ | ✅ | ❌ |
| 成绩单支持 | ✅ | ✅ | ✅ | ✅ |
| 轻量化（\ 备注：如果您将此与Claude Desktop或Claude Code一起使用，则不需要安装。看 Claude桌面配置 或 Claude代码配置 在......下面 |
选项1：直接与npx一起使用（推荐）
无需安装！您可以直接使用npx运行服务器：
npx @limecooler/yt-info-mcp选项2：从npm安装
npm install -g @limecooler/yt-info-mcp选项3：本地安装
- 克隆此存储库：
git clone https://github.com/Limecooler/yt-video-info.git
cd yt-video-info- 安装依赖项：
npm install- 构建TypeScript代码：
npm run buildClaude桌面配置
将以下内容添加到您的Claude Desktop配置文件中：
配置文件位置
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
选项1：使用npx（推荐-无需安装）
{
"mcpServers": {
"youtube-info": {
"command": "npx",
"args": ["-y", "@limecooler/yt-info-mcp@latest"]
}
}
}选项2：本地安装
{
"mcpServers": {
"youtube-info": {
"command": "node",
"args": ["/absolute/path/to/yt-video-info/dist/index.js"]
}
}
}Claude代码配置
要将此MCP服务器与Claude代码一起使用：
选项1：使用CLI快速设置（推荐）
只需在终端中运行以下命令：
claude mcp add yt-info-mcp -s user -- npx -y @limecooler/yt-info-mcp@latest这会自动将YouTube Info MCP服务器添加到您的全局Claude Code配置中。
选项2：手动全局配置
添加到全局Claude Code配置文件中：
配置文件位置：
- macOS/Linux:
~/.claude/config.json - 视窗:
%USERPROFILE%\.claude\config.json
{
"mcpServers": {
"youtube-info": {
"command": "npx",
"args": ["-y", "@limecooler/yt-info-mcp@latest"]
}
}
}这使得YouTube Info MCP服务器在您的所有Claude Code会话中都可用。
选项3：项目特定配置
添加到您的Claude Code项目配置中(.claude/project.json):
{
"mcpServers": {
"youtube-info": {
"command": "npx",
"args": ["-y", "@limecooler/yt-info-mcp@latest"]
}
}
}选项4：本地安装
如果您已在本地克隆了存储库：
{
"mcpServers": {
"youtube-info": {
"command": "node",
"args": ["./path/to/yt-video-info/dist/index.js"]
}
}
}配置后，您可以在Claude Code中使用该工具：
User: Get information about YouTube video dQw4w9WgXcQ
Claude Code: I'll fetch the video information using the YouTube Info MCP server.
[Uses the MCP tool to retrieve video metadata and transcript]用法
与Claude Desktop一起使用
配置后，您可以在Claude Desktop中使用该工具：
Please get information from YouTube video dQw4w9WgXcQ使用npm（命令行）
如果你通过npm全局安装：
# Run the MCP server directly
yt-info-mcp
# Or use with a tool that supports MCP
npx @modelcontextprotocol/cli connect yt-info-mcp用作图书馆
import { fetchVideoInfo, fetchTranscript } from '@limecooler/yt-info-mcp';
// Get video information
const { metadata, captionTracks } = await fetchVideoInfo('dQw4w9WgXcQ');
// Fetch transcript if available
if (captionTracks.length > 0) {
const transcript = await fetchTranscript(captionTracks[0]);
}工具将返回：
- 视频元数据（标题、作者、持续时间、观看次数、描述）
- 带时间戳的成绩单（如果可用）
- 如果视频不可用或没有转录，则显示错误详细信息
api参考
fetchVideoInfo(videoId: string)
获取视频元数据和可用字幕轨道。
参数：
videoId（string）：11个字符的YouTube视频ID
退货： Promise
metadata：包含视频信息的对象
- title （string）：视频标题 - author （string）：频道名称 - lengthSeconds （数字）：持续时间（秒） - viewCount （number）：查看次数 - description （string）：视频描述
captionTracks：可用字幕曲目阵列
- baseUrl （string）：获取成绩单的URL - languageCode （string）：语言代码（例如“en”、“es”）
投掷： YouTubeError 带有特定错误代码：
INVALID_ID：视频ID格式无效NOT_FOUND：视频不存在PRIVATE：视频是私人的AGE_RESTRICTED：受年龄限制的内容REGION_BLOCKED：区域阻止的内容
fetchTranscript(captionTrack: CaptionTrack)
获取并解析给定字幕轨道的文字记录。
参数：
captionTrack（CaptionTrack）：标题跟踪对象来自fetchVideoInfo
退货： Promise
text（string）：全文segments（array）：转录片段数组
- start （数字）：开始时间（秒） - text （字符串）：分段文本
错误处理示例：
try {
const { metadata, captionTracks } = await fetchVideoInfo('dQw4w9WgXcQ');
if (captionTracks.length > 0) {
const transcript = await fetchTranscript(captionTracks[0]);
console.log(transcript.text);
}
} catch (error) {
if (error.code === 'PRIVATE') {
console.log('This video is private');
}
}响应格式
{
"metadata": {
"title": "Video Title",
"author": "Channel Name",
"lengthSeconds": 215,
"viewCount": 1234567,
"description": "Video description..."
},
"transcript": {
"text": "Full transcript text...",
"segments": [
{
"start": 0.0,
"text": "First segment"
},
{
"start": 2.5,
"text": "Second segment"
}
]
},
"error": "Error message if transcript unavailable"
}错误处理
服务器处理各种错误情况：
- 视频ID格式无效
- 未找到视频（404）
- 私人或年龄限制的视频
- 无文字记录的视频
- 网络错误
发展
在开发模式下运行并自动重新加载：
npm run dev测试
运行全面测试：
npm test测试MCP协议通信：
npm run test:mcp启用调试日志记录：
MCP_DEBUG=true npm start故障排除
常见问题
安装npm后“找不到命令”
解决方案：将npm全局bin目录添加到PATH或使用npx：
# Check npm bin location
npm bin -g
# Or just use npx
npx @limecooler/yt-info-mcp空成绩单回复
可能的原因：
- 视频未启用字幕
- 视频在您所在地区受到地区限制
- YouTube正在限制您的请求速率
解决方案：检查视频是否在YouTube网站上有“CC”按钮。
“INVALID_ID”错误
解决方案：确保视频ID恰好为11个字符。从URL中提取它：
- ✅ 对的：
dQw4w9WgXcQ - ❌ 错误：
https://youtube.com/watch?v=dQw4w9WgXcQ
Claude Desktop中的连接被拒绝
解决方案：确保配置路径是绝对的，而不是相对的：
{
"mcpServers": {
"youtube-info": {
"command": "node",
"args": ["/Users/username/yt-video-info/dist/index.js"] // Full path
}
}
}速率限制错误
解决方案：实现请求之间的延迟或使用内置缓存：
// Videos are cached for 1 hour, transcripts for 2 hours
await fetchVideoInfo('video1');
// Second call uses cache
await fetchVideoInfo('video1');环境变量
| 变量 | 描述 | 默认值 | 示例 |
|---|---|---|---|
MCP_DEBUG | 启用stderr的调试日志记录 | false | MCP_DEBUG=true |
DEBUG | 备选调试标志 | false | DEBUG=true |
NODE_ENV | 环境模式 | production | NODE_ENV=development |
演出
- 启动时间：\<500ms（在M1 MacBook Air上测量）
- 内存使用：约50MB空闲，约100MB在活动请求期间
- 缓存TTL：视频信息（1小时），成绩单（2小时）
- 响应时间:
- 缓存：\<100ms - 新鲜获取：2-4s（取决于YouTube的响应时间）
- 并发请求：受限于Node.js事件循环
安全
安全考虑
- 没有凭据：不需要或存储API密钥或身份验证令牌
- 只读：仅执行GET/POST请求以检索公共数据
- 无用户数据：不收集或传输任何用户信息
- 内容过滤：尊重YouTube的年龄限制和隐私设置
- 安全依赖关系：依赖性最小，全部来自可信来源
- 输入验证：所有输入均已Zod模式验证
最佳实践
- 如果处理不受信任的视频ID，请在隔离环境中运行
- 监控速率限制以避免IP阻塞
- 使用环境变量进行配置，而不是硬编码值
局限性
- 依赖于YouTube的网络界面结构，这可能会发生变化
- 无法转录音频-仅下载现有字幕
- 如果过度使用，可能会受到YouTube的费率限制
- 无法访问年龄限制或私人视频
贡献
我们欢迎捐款！以下是您可以提供帮助的方式：
入门指南
- 分叉存储库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 进行更改
- 运行测试(
npm test) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
开发指南
- 遵循现有的代码风格和约定
- 为新功能添加测试
- 根据需要更新文档
- 保持提交的重点和描述性
- 在提交PR之前，确保所有测试都通过
报告问题
- 在创建新问题之前检查现有问题
- 包括重现错误的步骤
- 提供系统信息（Node.js版本、操作系统）
- 包括相关错误消息和日志
使用克劳德代码构建
整个项目是使用 克劳德代码Anthropic的人工智能编码助手。Claude Code通过内置的最佳实践和全面的测试实现了快速开发。
使用Claude代码进行更改
要使用Claude Code贡献或修改此存储库，请执行以下操作：
- 安装Claude代码 （如果你还没有）：
npm install -g @anthropic-ai/claude-code- 克隆并打开存储库:
git clone https://github.com/Limecooler/yt-video-info.git
cd yt-video-info
claude-code- 要求Claude Code进行更改:
- “添加对播放列表提取的支持” - “改进速率限制的错误处理” - “为刮板模块添加单元测试” - “更新InnerTube API实现”
- 克劳德代码将:
- 了解现有的代码库结构 - 遵循既定的模式和惯例 - 运行测试以确保更改不会破坏功能 - 根据需要更新文档 - 用描述性消息提交更改
为什么选择克劳德代码？
- 上下文感知：了解整个代码库并保持一致性
- 最佳实践：自动遵循TypeScript、MCP和npm约定
- 测试驱动：确保对变更进行测试和记录
- 高效：将开发时间从数小时缩短到几分钟
Claude代码会话示例
You: "Add a feature to download video thumbnails"
Claude Code: I'll add thumbnail download functionality to the MCP server.
[Claude Code analyzes the codebase, implements the feature, adds tests,
updates types, and creates a commit]
You: "Now add documentation for the new feature"
Claude Code: I'll update the README and add inline documentation.
[Updates all relevant documentation files]更新日志
看 发布 查看详细的版本历史。
最新版本：v1.1.1
- 🔧 修复了npx兼容性的可执行权限
- 🐛 已解决克劳德代码连接错误（MCP错误-32000）
- 📚 添加了简单的Claude Code CLI设置命令
v1.1.0版本
- 🐛 修复了使用YouTube的InnerTube API获取成绩单的问题
- ✨ 添加了Android客户端上下文，以提高可靠性
- 📚 通过徽章和更好的结构改进文档
许可证
麻省理工学院