使用说明

YouTube转录MCP服务器

一个强大的MCP（模型上下文协议）服务器，使用 yt-dlp，为Claude Desktop和HTTP客户端提供双传输支持。

特性

✅ 可靠的：用途 yt-dlp 获取成绩单，成绩单会定期更新以应对YouTube的变化
✅ 容器化：在Docker容器中运行，便于部署和移植
✅ 双重运输：支持Claude Desktop的SSE（服务器发送事件）和HTTP客户端的JSON-RPC
✅ 符合MCP标准：实现模型上下文协议，实现无缝的AI工具集成
✅ 多语言支持：获取任何可用语言（英语、法语、西班牙语等）的成绩单
✅ 安全：HTTP终结点的可选API密钥身份验证

快速开始

先决条件

码头工人安装
Docker Compose 安装
（可选） Node.js 用于Claude Desktop集成

安装

克隆存储库：

git clone <repository-url>
cd youtube-transcript-mcp

配置API密钥：

创建一个名为的文件 api_keys.json 在根目录中：
```
{
  "keys": [
    "your-super-secret-api-key-here"
  ]
}
```
构建并运行：
```
docker-compose up -d --build
```

验证服务器是否正在运行：

curl http://localhost:5000/test_transcript?videoId=dQw4w9WgXcQ

Docker部署

构建并运行

从项目根目录：

docker-compose up -d --build

服务器将在上运行 http://localhost:5000.

环境变量

编辑 docker-compose.yml 配置：

AUTH_ENABLED：设置为 false 禁用API密钥身份验证（默认值： true)

查看日志

docker logs <container-name>

停止服务器

docker-compose down

API 参考

服务器公开了支持不同传输协议的多个端点：

端点概述

端点	方法	传输	身份验证	目的
`/sse`	GET	SSE	无*	Claude桌面集成
`/`	POST	JSON-RPC 2.0	API密钥	n8n和HTTP客户端
`/test_transcript`	GET	REST	API密钥	快速测试

*SSE端点应由您的反向代理（例如Caddy、Nginx）保护

认证

服务器支持两种身份验证策略：

策略1：混合动力（默认）

SSE端点 (/sse)：未通过服务器身份验证-使用反向代理（Caddy、Nginx）进行保护
HTTP端点 (/, /test_transcript)：受保护 X-API-KEY 头球
最适合：具有不同身份验证方法的不同客户端（Claude Desktop通过Caddy，n8n通过API密钥）

策略2：仅反向代理

集 AUTH_ENABLED=false 在 docker-compose.yml 禁用服务器级身份验证
保护所有端点（包括 /sse, /, /test_transcript)使用您的反向代理
最适合：集中式身份验证，所有客户端的单一身份验证机制

看保护SSE端点查看详细的Caddy配置示例。

端点：GET/test_transcript

用于测试转录获取的简单REST端点。

参数：

videoId （必填）：YouTube视频ID
lang （可选）：语言代码（默认值： en)

例子：

curl -H "X-API-KEY: your-api-key" \
  "http://localhost:5000/test_transcript?videoId=dQw4w9WgXcQ&lang=en"

答复：

{
  "success": true,
  "transcript": [
    {
      "start": "00:00:00.000",
      "end": "00:00:02.500",
      "text": "Hello world"
    }
  ],
  "language": "en",
  "requested_language": "en"
}

注：如果请求的语言不可用，服务器会自动回退到常见的替代语言（en→fr→es→de→pt等）。这 language 字段显示获得的实际语言。

端点：POST/

适用于n8n和其他HTTP客户端的MCP兼容JSON-RPC 2.0端点。

支持的方法：

initialize：获取服务器功能
tools/list：列出可用工具
tools/call：执行 get_transcript 工具

示例-获取成绩单：

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_transcript",
      "arguments": {
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "language": "en"
      }
    }
  }' \
  http://localhost:5000/

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"transcript\":[{\"start\":\"00:00:00.000\",\"end\":\"00:00:02.500\",\"text\":\"Hello world\"}],\"language\":\"en\",\"requested_language\":\"en\"}"
      }
    ],
    "structuredContent": {
      "transcript": [
        {
          "start": "00:00:00.000",
          "end": "00:00:02.500",
          "text": "Hello world"
        }
      ],
      "language": "en",
      "requested_language": "en"
    }
  }
}

错误响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -1,
    "message": "Failed to fetch transcript in any available language",
    "details": "No subtitles for 'pt'",
    "attempted_languages": ["en", "fr", "es", "de", "pt"]
  }
}

Claude桌面集成

Claude Desktop使用SSE（服务器发送事件）连接到MCP服务器 mcp-remote 适配器。

安装说明

步骤1：确保已安装Node.js

Claude Desktop使用 npx 运行 mcp-remote.验证Node.js安装：

node --version

步骤2：配置Claude桌面

将以下内容添加到您的 claude_desktop_config.json:

对于macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

对于Windows：

%APPDATA%\Claude\claude_desktop_config.json

配置：

选项1：无身份验证（SSE端点可公开访问）：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-domain.com/sse"
      ]
    }
  }
}

选项2：使用HTTP基本身份验证（推荐）：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://username:password@your-domain.com/sse"
      ]
    }
  }
}

选项3：使用自定义头（API密钥、承载令牌等）：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "--header",
        "Authorization: Bearer your-token-here",
        "https://your-domain.com/sse"
      ]
    }
  }
}

重要提示： 替换 https://your-domain.com 使用您的实际服务器URL（例如，在Caddy或Nginx后面）。

步骤3：重新启动克劳德桌面

保存配置后，完全重新启动Claude Desktop。

步骤4：验证

在一次新的对话中 get_transcript 工具现在应该可用了。通过以下问题进行测试：

“你能从这段YouTube视频中获取文字记录吗：https://www.youtube.com/watch?v=dQw4w9WgXcQ"

保护SSE端点

由于默认情况下SSE端点未经过身份验证，请使用反向代理保护它们。

身份验证策略

您有两个身份验证选项：

选项A：仅保护 /sse 与Caddy（推荐）

使用Caddy进行身份验证 /sse/* 端点
保持 AUTH_ENABLED=true （默认）用于传统HTTP端点(/, /test_transcript)
优点：Claude Desktop使用Caddy auth，n8n/HTTP客户端使用X-API-KEY头

选项B：使用Caddy保护所有端点

使用Caddy对所有请求进行身份验证
集 AUTH_ENABLED=false 在 docker-compose.yml 禁用服务器级身份验证
优点：集中式身份验证，单身份验证机制

如果您希望为不同的客户端提供不同的身份验证方法，请选择选项A，或者选择选项B进行统一身份验证。

示例1：带基本身份验证的球童（仅限苏格兰和南方交易所-选项A）

生成密码哈希：

caddy hash-password

Caddyfile：

your-domain.com {
    reverse_proxy /sse/* localhost:5000

    # Add basic authentication
    basicauth /sse/* {
        alice $2a$14$hashed_password_here
    }
}

Claude桌面配置：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://alice:your-password@your-domain.com/sse"
      ]
    }
  }
}

示例2：带有API密钥头的Caddy（仅限SSE-选项A）

Caddyfile：

your-domain.com {
    @sse_auth {
        path /sse/*
        header X-API-Key "your-secret-api-key"
    }

    handle @sse_auth {
        reverse_proxy localhost:5000
    }

    # Reject requests without valid API key
    handle /sse/* {
        respond "Unauthorized" 401
    }

    # Allow other paths without auth (or add separate rules)
    reverse_proxy localhost:5000
}

Claude桌面配置：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "--header",
        "X-API-Key: your-secret-api-key",
        "https://your-domain.com/sse"
      ]
    }
  }
}

示例3:IP白名单（仅限苏格兰和南方交易所-选项A）

Caddyfile：

your-domain.com {
    @sse_trusted {
        path /sse/*
        remote_ip 192.168.1.0/24 10.0.0.0/8
    }

    handle @sse_trusted {
        reverse_proxy localhost:5000
    }

    handle /sse/* {
        respond "Forbidden" 403
    }

    reverse_proxy localhost:5000
}

Claude桌面配置：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-domain.com/sse"
      ]
    }
  }
}

示例4：使用基本身份验证保护所有端点（选项B）

如果要在反向代理级别集中所有身份验证，请使用此配置并禁用服务器级别的身份验证。

步骤1：生成密码哈希

caddy hash-password

步骤2：更新docker-compose.yml

version: '3.8'
services:
  web:
    build: .
    ports:
      - "5000:5000"
    environment:
      - AUTH_ENABLED=false  # Disable server-level auth

步骤3：配置Caddyfile

your-domain.com {
    # Apply basic auth to ALL endpoints
    basicauth /* {
        alice $2a$14$hashed_password_here
        bob $2a$14$another_hashed_password
    }

    reverse_proxy localhost:5000
}

Claude桌面配置：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://alice:your-password@your-domain.com/sse"
      ]
    }
  }
}

n8n HTTP请求配置：

方法：POST
统一资源定位符: https://your-domain.com/
认证：基本身份验证
- 用户名： alice
- 密码： your-password
标头: Content-Type: application/json
身体：（与之前相同的JSON-RPC格式）

注：通过此设置，您不再需要提供 X-API-KEY 头文件，因为所有身份验证都由Caddy处理。

示例5：使用API密钥头保护所有端点（选项B）

使用自定义标头而不是基本身份验证的替代方法。

第一步：更新docker-compose.yml

version: '3.8'
services:
  web:
    build: .
    ports:
      - "5000:5000"
    environment:
      - AUTH_ENABLED=false  # Disable server-level auth

步骤2：配置Caddyfile

your-domain.com {
    @authenticated {
        header X-API-Key "your-secret-api-key-here"
    }

    handle @authenticated {
        reverse_proxy localhost:5000
    }

    # Reject all requests without valid API key
    handle {
        respond "Unauthorized" 401
    }
}

Claude桌面配置：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "--header",
        "X-API-Key: your-secret-api-key-here",
        "https://your-domain.com/sse"
      ]
    }
  }
}

n8n HTTP请求配置：

方法：POST
统一资源定位符: https://your-domain.com/
标头:
- Content-Type: application/json
- X-API-Key: your-secret-api-key-here
身体：（与之前相同的JSON-RPC格式）

n8n集成

使用HTTP请求节点将此MCP服务器集成到n8n工作流中。

HTTP请求节点设置

添加HTTP请求节点 到您的工作流程
配置节点：
- 方法: POST
- 统一资源定位符: https://your-domain.com/
- 认证：无（使用API键的标头）
添加标题：

名称值

Content-Type application/json

X-API-KEY your-api-key-here

设置正文（JSON）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_transcript",
    "arguments": {
      "url": "{{ $json.videoUrl }}",
      "language": "en"
    }
  }
}

工作流示例

脚本： 从通过webhook提交的YouTube URL中提取文字记录

Webhook触发器 -接收YouTube URL
HTTP 请求 -调用此MCP服务器
设置节点 -从回复中提取文字记录
过程记录 -分析、总结或存储

响应处理

答案将在 result.structuredContent.transcript 字段：

// n8n expression to access transcript
{{ $json.result.structuredContent.transcript }}

配置

api_keys.json

包含用于HTTP终结点身份验证的有效API密钥。

{
  "keys": [
    "production-key-1",
    "production-key-2",
    "development-key"
  ]
}

docker-compose.yml

配置环境变量：

version: '3.8'
services:
  web:
    build: .
    ports:
      - "5000:5000"
    environment:
      - AUTH_ENABLED=false  # Set to 'false' to disable authentication

支持的语言

您可以获取YouTube支持的任何语言的成绩单。常用代码：

en -英语
fr -法语
es -西班牙语
de -德语
ja -日语
ko -朝鲜语
zh -中文
ar -阿拉伯语

例子：

curl -H "X-API-KEY: your-key" \
  "http://localhost:5000/test_transcript?videoId=dQw4w9WgXcQ&lang=fr"

故障排除

Docker容器无法启动

检查日志：

docker logs <container-name>

常见问题：

缺失 api_keys.json 文件
端口5000已在使用中
Docker配置无效

克劳德桌面无法连接

验证：

可以通过配置的URL访问服务器
Node.js和 npx 可用的
claude_desktop_config.json 语法正确
Claude Desktop已完全重新启动

测试SSE端点：

curl https://your-domain.com/sse

n8n返回401未经授权

检查：

X-API-KEY 标题设置正确
API密钥存在于 api_keys.json
AUTH_ENABLED 未设置为 false

成绩单不可用

可能的原因：

视频没有字幕/字幕
请求的语言不可用
视频是私人的或受限制的
yt-dlp 需要更新

解决方案： 试试看 lang=en （最常见的是自动生成的英文字幕）

许可证

这个项目是开源的，可以在MIT许可证下使用。

贡献

欢迎投稿！请随时提交拉取请求。

致谢

内置于 FastMCP -Python MCP SDK
用途 yt-dlp 用于可靠的转录提取
实施模型上下文协议

名称	值
`Content-Type`	`application/json`
`X-API-KEY`	`your-api-key-here`

使用说明

YouTube转录MCP服务器

特性

目录

快速开始

先决条件

安装

Docker部署

构建并运行

环境变量

查看日志

停止服务器

API 参考

端点概述

认证

端点：GET/test_transcript

端点：POST/

Claude桌面集成

安装说明

保护SSE端点

身份验证策略

示例1：带基本身份验证的球童（仅限苏格兰和南方交易所-选项A）

示例2：带有API密钥头的Caddy（仅限SSE-选项A）

示例3:IP白名单（仅限苏格兰和南方交易所-选项A）

示例4：使用基本身份验证保护所有端点（选项B）

示例5：使用API密钥头保护所有端点（选项B）

n8n集成

HTTP请求节点设置

工作流示例

响应处理

配置

api_keys.json

docker-compose.yml

支持的语言

故障排除

Docker容器无法启动

克劳德桌面无法连接

n8n返回401未经授权

成绩单不可用

许可证

贡献

致谢

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器