Skip to main content
Glama
Sign In
subtitle-analyzer

subtitle-analyzer

by hgao1604
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Subtitle Analyzer MCP

基于 yt-dlp 的字幕分析 MCP 服务器，支持 YouTube 和 Bilibili 平台。

功能特性

  • 🎬 字幕提取 - 从视频提取字幕（支持手动字幕和自动生成字幕）

  • 🔍 时间戳搜索 - 搜索关键词并定位到具体时间点

  • 📋 视频信息 - 获取视频标题、时长、描述等元信息

  • 🌍 多语言支持 - 支持中文、英文、日文等多种语言字幕

Related MCP server: youtube-mcp

安装

前置要求

  1. Python 3.10+

  2. yt-dlp（系统级安装）

# 安装 yt-dlp
pip install yt-dlp
# 或者使用 brew (macOS)
brew install yt-dlp

安装 MCP

# 克隆或下载项目
cd subtitle-analyzer-mcp

# 安装依赖
pip install -e .

配置

Claude Desktop

编辑配置文件：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "subtitle-analyzer": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/subtitle-analyzer-mcp"
    }
  }
}

或者使用 uv（推荐）：

{
  "mcpServers": {
    "subtitle-analyzer": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/subtitle-analyzer-mcp", "python", "-m", "src.server"]
    }
  }
}

Claude Code

# 添加 MCP 服务器
claude mcp add subtitle-analyzer -- python -m src.server --cwd /path/to/subtitle-analyzer-mcp

认证配置

YouTube 和 Bilibili 的部分视频需要登录才能访问。由于 MCP 服务器运行在后台进程中，无法直接访问浏览器 cookies，因此需要预先导出 cookies 文件。

认证优先级

系统按以下优先级查找认证信息：

  1. cookies_file 参数 - 工具调用时直接指定

  2. YT_DLP_COOKIES 环境变量 - 推荐用于 MCP 环境

  3. 浏览器 cookies - 仅本地开发环境可用

导出 Cookies 文件

# 从 Chrome 导出 cookies（需要先登录 YouTube/Bilibili）
# 使用具体视频 URL 比首页更快（避免解析推荐列表）
yt-dlp --cookies-from-browser chrome --cookies ~/.yt-cookies.txt \
  --skip-download "https://www.youtube.com/watch?v=jNQXAC9IVRw"

# 设置文件权限（保护敏感信息）
chmod 600 ~/.yt-cookies.txt

⚠️ 注意: Cookies 会过期（通常 1-2 周），需要定期重新导出。

配置方式

方式 1: 环境变量（推荐）

# 在 shell 配置文件中添加 (~/.zshrc 或 ~/.bashrc)
export YT_DLP_COOKIES=~/.yt-cookies.txt

方式 2: Claude Desktop 配置

{
  "mcpServers": {
    "subtitle-analyzer": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/subtitle-analyzer-mcp",
      "env": {
        "YT_DLP_COOKIES": "/Users/yourname/.yt-cookies.txt"
      }
    }
  }
}

方式 3: Claude Code 配置

# 注册时通过 env 命令注入环境变量
claude mcp add subtitle-analyzer -- \
  env YT_DLP_COOKIES=/path/to/.yt-cookies.txt \
  python -m src.server --cwd /path/to/subtitle-analyzer-mcp

方式 4: 工具调用时指定

在调用工具时直接传入 cookies_file 参数：

{
  "url": "https://www.youtube.com/watch?v=xxxxx",
  "cookies_file": "/path/to/.yt-cookies.txt"
}

使用示例

1. 提取字幕

请提取这个视频的字幕：https://www.youtube.com/watch?v=xxxxx

2. 搜索时间戳

在这个视频中搜索"机器学习"出现的位置：https://www.bilibili.com/video/BVxxxxx

3. 获取视频信息

获取这个视频的基本信息：https://www.youtube.com/watch?v=xxxxx

4. 内容摘要（配合 Claude 使用）

提取这个视频的字幕并生成摘要：https://www.youtube.com/watch?v=xxxxx

工具列表

工具名称

功能

参数

extract_subtitles

提取字幕

url, lang?, format?, cookies_file?

search_timestamp

搜索关键词时间戳

url, keywords, context_lines?, cookies_file?

get_video_info

获取视频信息

url, cookies_file?

list_available_subtitles

列出可用字幕

url, cookies_file?

带 ? 的参数为可选参数

常见问题

Q: MCP 环境下提示认证失败或无法访问？

A: MCP 服务器运行在后台进程，无法直接访问浏览器 cookies。解决方法：

  1. 导出 cookies 文件：

    yt-dlp --cookies-from-browser chrome --cookies ~/.yt-cookies.txt \
  --skip-download "https://www.youtube.com"

  2. 配置 YT_DLP_COOKIES 环境变量（见认证配置章节）

Q: Bilibili 视频无法提取字幕？

A: Bilibili 部分视频需要登录才能访问字幕。请参考认证配置章节设置 cookies。

Q: 提示"无法提取字幕"？

A: 可能原因：

  1. 视频本身没有字幕 - 使用 list_available_subtitles 工具检查

  2. 需要登录认证 - 配置 cookies 文件

  3. 网络连接问题

  4. Cookies 已过期 - 重新导出 cookies 文件

Q: 自动字幕质量不好？

A: 自动生成的字幕（ASR）质量取决于平台算法。建议：

  1. 优先使用手动上传的字幕

  2. 使用 list_available_subtitles 查看可用选项

Q: Cookies 多久需要更新一次？

A: 通常 1-2 周后 cookies 会过期，届时需要重新执行导出命令。如果突然出现认证失败，请先尝试重新导出 cookies。

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 本地测试服务器
python -m src.server

License

MIT License

Available Tools

4 tools
extract_subtitlesA

从视频 URL 提取字幕。 支持平台：YouTube、Bilibili 返回：完整字幕文本，包含时间戳

认证配置（按优先级）：

  1. cookies_file 参数

  2. YT_DLP_COOKIES 环境变量

  3. 浏览器 cookies（仅本地环境）

参数：

  • url: 视频链接 (必填)

  • lang: 首选字幕语言，如 'zh', 'en', 'ja' (可选，默认自动检测)

  • format: 输出格式 'text' (纯文本) 或 'srt' (带时间戳) (可选，默认 'srt')

  • cookies_file: cookies 文件路径，用于认证需要登录的视频 (可选)

Inputs: url (required), lang, format, cookies_file.

get_video_infoA

获取视频的基本信息，包括标题、时长、描述等。

认证配置（按优先级）：

  1. cookies_file 参数

  2. YT_DLP_COOKIES 环境变量

  3. 浏览器 cookies（仅本地环境）

参数：

  • url: 视频链接 (必填)

  • cookies_file: cookies 文件路径，用于认证需要登录的视频 (可选)

Inputs: url (required), cookies_file.

list_available_subtitlesA

列出视频可用的所有字幕语言。 用于了解视频有哪些字幕可以提取。

认证配置（按优先级）：

  1. cookies_file 参数

  2. YT_DLP_COOKIES 环境变量

  3. 浏览器 cookies（仅本地环境）

参数：

  • url: 视频链接 (必填)

  • cookies_file: cookies 文件路径，用于认证需要登录的视频 (可选)

Inputs: url (required), cookies_file.

search_timestampA

在字幕中搜索关键词，返回匹配的时间戳位置。 用于快速定位视频中提到某个话题的时间点。

认证配置（按优先级）：

  1. cookies_file 参数

  2. YT_DLP_COOKIES 环境变量

  3. 浏览器 cookies（仅本地环境）

参数：

  • url: 视频链接 (必填)

  • keywords: 要搜索的关键词列表 (必填)

  • context_lines: 返回匹配位置前后的上下文行数 (可选，默认 2)

  • cookies_file: cookies 文件路径，用于认证需要登录的视频 (可选)

Inputs: url (required), keywords (required), cookies_file, context_lines.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation2/5

    The extract_subtitles tool has a 'get_video_info' parameter that overlaps with the separate get_video_info tool, causing ambiguity. Additionally, extract_subtitles and search_timestamp both involve subtitle content but with different purposes, though this is less problematic.

    Naming Consistency5/5

    All tool names use consistent snake_case and follow a verb_noun pattern (extract_subtitles, get_video_info, list_available_subtitles, search_timestamp), making them predictable.

    Tool Count5/5

    With 4 tools covering extraction, listing, info retrieval, and searching, the count is appropriate for the server's subtitle analysis purpose, neither too many nor too few.

    Completeness4/5

    The set covers core subtitle analysis operations, but missing features like subtitle translation or editing are minor gaps given the 'analyzer' focus. The inclusion of format options and search is good.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • YouTube MCP

      adshaa
      A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables users to retrieve YouTube transcripts and perform video or channel searches without requiring Google API keys. It supports transcript chunking and provides tools for detailed video content analysis and channel metadata extraction.
      5
      30 npm
      4
      MIT

    • youtube-mcp

      kzmshx
      A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables the extraction of transcripts and detailed metadata from YouTube videos. It allows users to retrieve video information like titles and descriptions, as well as transcripts with optional timestamps and language selection.
      2
      14 PyPI
      MIT

    • youtube-mcp

      ericluciano
      A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server for extracting YouTube video transcripts, metadata, and performing visual analysis using Gemini Vision or local Whisper models. It enables users to process video content through various tools for subtitle retrieval and frame analysis.
      23 npm
      MIT