YouTube信息MCP服务器
一个轻量级的MCP服务器,通过web抓取提取YouTube视频元数据和转录本,具有强大的错误处理、缓存和重试逻辑,无需API密钥或外部依赖性。
目录
- 🚀 快速开始
- 先决条件
- 特性
- 运作原理
- 与备选方案的比较
- 安装
- Claude桌面配置
- Claude代码配置
- 用法
- api参考
- 响应格式
- 错误处理
- 发展
- 故障排除
- 环境变量
- 演出
- 安全
- 局限性
- 贡献
- 使用克劳德代码构建
- 更新日志
- 许可证
🚀 快速开始```bash
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相同)可靠地获取视频数据:
1. **页面提取**:检索YouTube视频页面HTML
1. **API密钥提取**:提取 `INNERTUBE_API_KEY` 从页面源
1. **InnerTube请求**:向发出经过身份验证的POST请求 `/youtubei/v1/player`
1. **Android环境**:使用Android客户端上下文(`clientName: "ANDROID"`)为了更好地获取成绩单
1. **回退策略**:如果InnerTube失败,则返回HTML抓取
这种方法比直接获取字幕URL更可靠,因为它模仿了YouTube官方应用程序检索数据的方式。
## 与备选方案的比较
功能 · yt-info-mcp · yt-dlp · youtube-dl · youtube API
不需要API密钥 · ✅ · ✅ · ✅ · ❌
成绩单支持 · ✅ · ✅ · ✅ · ✅
轻量化(\<10MB) · ✅ · ❌ · ❌ · ✅
MCP协议 · ✅ · ❌ · ❌ · ❌
不需要Python · ✅ · ❌ · ❌ · ✅
Types/JavaScript✅ · ❌ · ❌ · ✅
内置缓存 · ✅ · ❌ · ❌ · ❌
## 安装
> **备注**:如果您将此与Claude Desktop或Claude Code一起使用,则不需要安装。看 Claude桌面配置 或 Claude代码配置 在......下面
### 选项1:直接与npx一起使用(推荐)
无需安装!您可以直接使用npx运行服务器:```bash
npx @limecooler/yt-info-mcp
选项2:从npm安装```bash
npm install -g @limecooler/yt-info-mcp
### 选项3:本地安装
1. 克隆此存储库:```bash
git clone https://github.com/Limecooler/yt-video-info.git
cd yt-video-info
- 安装依赖项:```bash
npm install
3. 构建TypeScript代码:```bash
npm run build
Claude桌面配置
将以下内容添加到您的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(推荐-无需安装)```json
{
"mcpServers": {
"youtube-info": {
"command": "npx",
"args": ["-y", "@limecooler/yt-info-mcp@latest"]
}
}
}
### 选项2:本地安装```json
{
"mcpServers": {
"youtube-info": {
"command": "node",
"args": ["/absolute/path/to/yt-video-info/dist/index.js"]
}
}
}
Claude代码配置
要将此MCP服务器与Claude代码一起使用:
选项1:使用CLI快速设置(推荐)
只需在终端中运行以下命令:```bash
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````json
{
"mcpServers": {
"youtube-info": {
"command": "npx",
"args": ["-y", "@limecooler/yt-info-mcp@latest"]
}
}
}
这使得YouTube Info MCP服务器在您的所有Claude Code会话中都可用。
选项3:项目特定配置
添加到您的Claude Code项目配置中(.claude/project.json):```json
{
"mcpServers": {
"youtube-info": {
"command": "npx",
"args": ["-y", "@limecooler/yt-info-mcp@latest"]
}
}
}
### 选项4:本地安装
如果您已在本地克隆了存储库:```json
{
"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全局安装:```bash
Run the MCP server directly
yt-info-mcp
Or use with a tool that supports MCP
npx @modelcontextprotocol/cli connect yt-info-mcp
### 用作图书馆```javascript
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: VideoMetadata; captionTracks: CaptionTrack[] }>
metadata:包含视频信息的对象title(string):视频标题author(string):频道名称lengthSeconds(数字):持续时间(秒)viewCount(number):查看次数description(string):视频描述captionTracks:可用字幕曲目阵列baseUrl(string):获取成绩单的URLlanguageCode(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(字符串):分段文本
错误处理示例:```javascript
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');
}
}
## 响应格式```json
{
"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)
- 私人或年龄限制的视频
- 无文字记录的视频
- 网络错误
发展
在开发模式下运行并自动重新加载:```bash
npm run dev
### 测试
运行全面测试:```bash
npm test
测试MCP协议通信:```bash
npm run test:mcp
启用调试日志记录:```bash
MCP_DEBUG=true npm start
故障排除
常见问题
安装npm后“找不到命令”
解决方案:将npm全局bin目录添加到PATH或使用npx:```bash
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中的连接被拒绝
**解决方案**:确保配置路径是绝对的,而不是相对的:```json
{
"mcpServers": {
"youtube-info": {
"command": "node",
"args": ["/Users/username/yt-video-info/dist/index.js"] // Full path
}
}
}
速率限制错误
解决方案:实现请求之间的延迟或使用内置缓存:```javascript
// 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的费率限制
- 无法访问年龄限制或私人视频
## 贡献
我们欢迎捐款!以下是您可以提供帮助的方式:
### 入门指南
1. 分叉存储库
1. 创建功能分支(`git checkout -b feature/amazing-feature`)
1. 进行更改
1. 运行测试(`npm test`)
1. 提交您的更改(`git commit -m 'Add amazing feature'`)
1. 推到分支(`git push origin feature/amazing-feature`)
1. 打开拉取请求
### 开发指南
- 遵循现有的代码风格和约定
- 为新功能添加测试
- 根据需要更新文档
- 保持提交的重点和描述性
- 在提交PR之前,确保所有测试都通过
### 报告问题
- 在创建新问题之前检查现有问题
- 包括重现错误的步骤
- 提供系统信息(Node.js版本、操作系统)
- 包括相关错误消息和日志
## 使用克劳德代码构建
整个项目是使用 克劳德代码Anthropic的人工智能编码助手。Claude Code通过内置的最佳实践和全面的测试实现了快速开发。
### 使用Claude代码进行更改
要使用Claude Code贡献或修改此存储库,请执行以下操作:
1. **安装Claude代码** (如果你还没有):```bash
npm install -g @anthropic-ai/claude-code
- 克隆并打开存储库:```bash
git clone https://github.com/Limecooler/yt-video-info.git
cd yt-video-info
claude-code
1. **要求Claude Code进行更改**:
- “添加对播放列表提取的支持”
- “改进速率限制的错误处理”
- “为刮板模块添加单元测试”
- “更新InnerTube API实现”
1. **克劳德代码将**:
- 了解现有的代码库结构
- 遵循既定的模式和惯例
- 运行测试以确保更改不会破坏功能
- 根据需要更新文档
- 用描述性消息提交更改
### 为什么选择克劳德代码?
- **上下文感知**:了解整个代码库并保持一致性
- **最佳实践**:自动遵循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客户端上下文,以提高可靠性
- 📚 通过徽章和更好的结构改进文档
许可证
麻省理工学院
