Skip to main content
Glama

# bilibili-learning-mcp

CI License: MIT Python MCP

让 Codex、Claude Desktop 等 MCP 客户端直接「看」B 站学习视频的 server: 搜索视频、读取简介、抓取字幕、查看热门评论。

只提供数据,不调用任何 LLM API。 总结、笔记、问答全部由客户端模型完成; Server 不含任何模型调用、不下载视频、不持久化内容。

状态:0.1.0(Alpha),当前仅支持 stdio 传输。

它能做什么

工具

作用

登录 Cookie

search_videos

关键词搜索,返回标题 / UP主 / BV号 / 时长 / 播放量

⚪ 可选

get_video_info

标题、简介、UP主、分P(含 cid)、播放/点赞/收藏、时长

❌ 不需要

get_subtitles

字幕逐行输出 [mm:ss] 文本(超过 1 小时为 [h:mm:ss]),支持按秒级时间段截取

⚠️ 通常需要

get_hot_comments

按点赞排序的热门评论,用来判断视频口碑

❌ 不需要

搜索、视频信息、热门评论均可匿名使用;字幕(尤其 AI 字幕)需要登录 Cookie。 配置 Cookie 还能降低搜索触发风控的概率。

典型用法:

帮我找「线性代数 期末速成」的视频,挑播放量最高的那个,读字幕整理一份带时间戳的笔记。

Related MCP server: bilibili-info-mcp

快速开始

1. 准备环境

  • Python 3.10+

  • uv

  • 可选:Node.js 18+(仅使用 MCP Inspector 调试时需要)

2. 安装

git clone https://github.com/Unc1e-2ack/bilibili-learning-mcp.git
cd bilibili-learning-mcp
uv sync

3. 接入客户端

Claude Desktop

编辑 claude_desktop_config.json(Windows:%APPDATA%\Claude\;macOS:~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "bilibili-learning": {
      "command": "uv",
      "args": [
        "--directory",
        "G:\\path\\to\\bilibili-learning-mcp",
        "run",
        "bilibili-learning-mcp"
      ]
    }
  }
}

macOS / Linux 把示例里的 Windows 路径换成 /path/to/...。如果客户端找不到 uv, 把 command 换成 uv 的绝对路径。

需要字幕时,在同一层级加上 env:

"env": {
  "BILIBILI_COOKIE": "SESSDATA=xxx; bili_jct=yyy"
}

Codex

codex mcp add bilibili-learning -- uv --directory "/path/to/bilibili-learning-mcp" run bilibili-learning-mcp

需要字幕时,先移除再带 Cookie 注册:

codex mcp remove bilibili-learning
codex mcp add bilibili-learning \
  --env BILIBILI_COOKIE="SESSDATA=xxx; bili_jct=yyy" \
  -- uv --directory "/path/to/bilibili-learning-mcp" run bilibili-learning-mcp

Windows 下路径建议用绝对路径并加引号(例如 "G:\path\to\bilibili-learning-mcp")。 注册后新开一个会话才会生效。

其它 MCP 客户端

stdio 命令:

uv --directory /path/to/bilibili-learning-mcp run bilibili-learning-mcp
  1. 浏览器登录 bilibili.com;

  2. 按 F12 打开开发者工具 → Network,筛选 api.bilibili.com;

  3. 随便点一个请求,复制请求头里完整的 Cookie: 值(至少包含 SESSDATA);

  4. 复制配置模板并填入:

cp .env.example .env
# 或者在 shell 里导出
export BILIBILI_COOKIE='SESSDATA=xxx; bili_jct=yyy; ...'

⚠️ Cookie 等同于账号凭证。.env 已在 .gitignore 中,不要提交、不要贴到 issue 里。

使用示例

我:帮我总结一下 BV1xx411c7mD 讲了什么,要带时间戳。

模型:-> get_video_info(bv_id="BV1xx411c7mD")
      -> get_subtitles(bv_id="BV1xx411c7mD", page=1)
      -> 用字幕生成带 [mm:ss] 的笔记

BV1xx411c7mD 只是占位示例,请换成实际 BV 号。没有字幕的视频会在 get_subtitles 处得到明确提示。

字幕过长时会自动截断到 8000 行并提示总行数,可以用 start_sec / end_sec 分段读取:

get_subtitles(bv_id="BV1xx411c7mD", page=1, start_sec=600, end_sec=1200)

常见问题

一定要配置 Cookie 吗? 不需要。搜索、视频信息、热门评论都能匿名使用;字幕接口通常需要登录 Cookie,AI 字幕尤其如此。

为什么提示「没有可用字幕」? 可能该视频没有生成字幕、该分P没有字幕,或者当前请求缺少有效 Cookie。可以换一个视频,或改用 get_video_info 看简介。

会不会导致账号被封? 项目只调用只读 Web 接口,不下载视频、不批量抓取,所有请求串行间隔 ≥ 1 秒。仍建议低频使用并自行承担风险。

支持 HTTP / SSE 吗? 当前只支持 stdio。如果客户端只接受 HTTP,可以自行用 mcp-proxy 之类的工具转换。

支持哪些平台? Windows、macOS、Linux;CI 覆盖 Python 3.10–3.13。

错误处理

工具层会把所有错误转成给模型看的中文说明,而不是抛异常或只返回错误码:

情况

返回

需要登录但未配置 Cookie

提示 BILIBILI_COOKIE 的配置方法

匿名搜索被 412 / 风控拦截

提示配置 Cookie 后重试

-101 未登录 / Cookie 失效

提示重新获取 Cookie

-352 WBI 校验失败

提示稍后重试,持续失败则更新 Cookie

网络超时(10s)

提示稍后重试

返回非 JSON

说明可能被风控页拦截

无字幕

提示改用 get_video_info 看简介

设计说明

  • 匿名优先,Cookie 可选:搜索默认匿名请求,配置了 Cookie 会自动携带,用来提高风控下的成功率。

  • 请求节流:所有请求串行间隔 ≥ 1 秒,避免给 B 站造成压力。

  • WBI 签名:从 nav 接口取 img_key / sub_key,缓存 6 小时,按社区文档的置换表计算 w_rid(参考 bilibili-API-collect)。

  • 凭据最小暴露:Cookie 只发往 api.bilibili.com,请求字幕 CDN 时不会携带。

  • 防御式解析:所有接口字段用 .get() 读取,字段缺失不会 KeyError。

  • 不做的事:不下载视频、不落盘任何内容、不调用 LLM、不上传用户数据。

  • BV 号:支持完整链接,自动提取;BV 前缀统一大写,但主体大小写保持不变(BV 号主体区分大小写,改动会导致查不到视频)。

开发

uv sync                     # 安装依赖(含开发依赖)
uv run pytest               # 36 个测试,全部 mock,不请求真实 B 站
uv run ruff check .         # 静态检查
uv run ruff format --check .  # 格式检查
uv run mcp dev main.py      # MCP Inspector(需要 Node.js)
uv run main.py              # 以 stdio 方式启动

项目结构:

.
├── src/bilibili_learning_mcp/
│   ├── __init__.py
│   ├── server.py        # FastMCP 实例 + 4 个 tool
│   ├── bilibili_api.py  # HTTP 封装、节流、错误映射
│   ├── wbi_sign.py      # WBI 签名
│   └── py.typed
├── tests/
│   ├── conftest.py
│   ├── test_api.py
│   ├── test_tools.py
│   └── test_wbi_sign.py
├── .github/
│   ├── workflows/ci.yml
│   └── ISSUE_TEMPLATE/
├── main.py
├── pyproject.toml
├── uv.lock
├── CHANGELOG.md
├── LICENSE
└── README.md

贡献与安全

合规与免责

  • 本项目仅调用 B 站公开 Web 接口,用于个人学习与内容检索;

  • 请遵守 B 站用户协议 与 robots.txt,不要高频抓取;

  • 字幕与评论版权归原作者所有,请勿二次分发;

  • 本项目与哔哩哔哩官方无关。

License

MIT

Available Tools

4 tools
get_hot_commentsGet hot Bilibili commentsA

按点赞数排序返回视频的热门评论,用来判断视频质量和观众口碑。

何时调用:
    - 用户想知道某个视频「值不值得看」「大家评价怎么样」时。
    - 总结完视频内容后,想补充观众反馈作为参考时。
    - 不要用它替代 get_subtitles 做内容总结:评论只有观点,没有讲解内容。

参数:
    bv_id: BV 号或完整链接,例如 "BV1GJ411x7h7"。
    limit: 返回条数,范围 1-49,默认 10。

返回示例:
    《线性代数的本质》热门评论(按点赞排序,共 1234 条,返回前 2 条):

    1. 👍 892 | 某用户
       讲得比我们老师清楚多了
    2. 👍 431 | 另一个用户
       第三集开始有点快,建议 0.75 倍速

失败时:
    返回以「获取评论失败:」开头的说明;评论区关闭时会明确告知,
    此时可以改用 get_subtitles 或 get_video_info 了解内容。

Inputs: bv_id (required), limit. Returns: result

get_subtitlesRead Bilibili subtitlesA

读取视频某一 P 的字幕,按 "[mm:ss] 文本" 逐行返回,适合做带时间戳的笔记。

何时调用:
    - 用户要总结视频、做学习笔记、提取知识点时(这是最重要的素材来源,优先于简介)。
    - 需要引用原话或定位具体时间点时。
    - 用户问「这个视频讲了什么」而 get_video_info 的简介太简略时。

参数:
    bv_id: BV 号或完整链接,例如 "BV1GJ411x7h7"。
    page: 分P序号,从 1 开始,默认 1。先用 get_video_info 查看共几 P。
    start_sec: 只返回起始时间 >= 该秒数的字幕,例如 600 表示 10:00 之后。
    end_sec: 只返回起始时间 <= 该秒数的字幕,例如 1200 表示 20:00 之前。
        字幕过长时可分段读取:先 0-600,再 600-1200……

返回示例:
    《线性代数的本质》第 1 P(向量是什么)字幕 - 中文(自动生成),共 412 行
    时间范围:00:00 - 06:52

    [00:00] 这个视频我们来聊向量
    [00:03] 首先从物理学的角度

注意:
    - AI 字幕需要登录 Cookie;部分视频没有字幕,此时会返回明确提示。
    - 单次最多返回 8000 行,超出会截断并说明总行数,请用 start_sec/end_sec 分段读取。

失败时:
    返回以「读取字幕失败:」开头的说明,并给出下一步建议。

Inputs: bv_id (required), page, end_sec, start_sec. Returns: result

get_video_infoGet Bilibili video infoA

读取单个 B 站视频的详细信息:标题、简介、UP主、分P列表(含 cid)、互动数据、时长。

何时调用:
    - 用户给了 BV 号或视频链接,想了解这个视频讲了什么时。
    - 调用 get_subtitles 或 get_hot_comments 之前,先确认分P数量和 cid。
    - 视频没有字幕时,用简介判断内容是否值得看。

参数:
    bv_id: BV 号或完整链接。支持 "BV1GJ411x7h7"、
        "https://www.bilibili.com/video/BV1GJ411x7h7"、
        "https://www.bilibili.com/video/BV1GJ411x7h7?p=2" 等写法。
        注意 BV 号主体区分大小写,请原样复制,不要手打。

返回示例:
    标题:线性代数的本质
    BV号:BV1GJ411x7h7 | AV号:8047632
    UP主:3Blue1Brown
    时长:1:02:03(3723 秒)
    播放:1234.5万 | 点赞:8.9万 | 收藏:3.2万 | 投币:1.1万 | 评论:4321
    发布时间:2020-05-01
    链接:https://www.bilibili.com/video/BV1GJ411x7h7

    简介:
    (最多 800 字,超出会标注「已截断」)

    分P列表(共 2 P):
    P1 | cid=12345678 | 00:12:34 | 向量是什么
    P2 | cid=12345679 | 00:15:01 | 线性组合

失败时:
    返回以「获取视频信息失败:」开头的说明。BV 号格式错误时会提示正确写法,
    视频不存在或被删除时会说明原因,不要用同样的参数重试。

Inputs: bv_id (required). Returns: result

search_videosSearch Bilibili videosA

在 B 站搜索学习类视频,返回标题、UP主、BV号、时长、播放量和链接。

何时调用:
    - 用户想找某个主题的教程、课程或讲解,而手上还没有具体视频时,先用本工具。
    - 需要给用户一份候选清单让他挑选时。
    - 已经知道 BV 号时不要用本工具,直接调用 get_video_info。

参数:
    keyword: 搜索关键词,建议 1-4 个词,例如 "线性代数 期末速成"、"MIT 6.824"。
        支持中英文和空格;不要传 URL 或 BV 号。无需 Cookie 也能搜索,
        配置 Cookie 可提高被风控时的成功率。
    limit: 返回条数,范围 1-50,默认 5。给用户做选择时 5-10 条足够。

返回示例:
    搜索「线性代数」找到 2 个视频:

    1. 线性代数 期末速成(4小时)
       UP主:某老师 | 时长:4:12:30 | 播放:120.5万
       BV号:BV1xx411c7mD
       链接:https://www.bilibili.com/video/BV1xx411c7mD

失败时:
    返回以「搜索失败:」开头的中文说明。搜索可匿名使用;若被 B 站风控拦截,
    会提示配置 BILIBILI_COOKIE。请把配置方法转告用户,不要用相同参数反复重试。

Inputs: keyword (required), limit. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct resource: discovery (search_videos), metadata (get_video_info), content (get_subtitles), and social proof (get_hot_comments). The descriptions explicitly draw boundaries, e.g. 'already know the BV id → don't use search_videos' and 'don't use get_hot_comments as a substitute for get_subtitles'.

    Naming Consistency5/5

    All four names follow a consistent snake_case verb_noun pattern: search_videos, get_video_info, get_subtitles, get_hot_comments. The verb choice (search vs get) also maps meaningfully to the operation type.

    Tool Count5/5

    Four tightly scoped tools that each earn their place in a single linear workflow (find → inspect → read → validate). Nothing feels redundant or missing at the tool-count level for a video-learning server.

    Completeness4/5

    The surface covers the full learning lifecycle: discover videos, get metadata/分P info, read timestamped subtitles with pagination, and check audience feedback. Minor gaps exist — no way to list a UP主's other videos, no cross-video/collection search, and no tool to persist notes — but agents can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for fetching Bilibili video metadata and subtitles. Supports running locally via stdio transport for integration with MCP clients like Cursor or Claude Desktop.
      1
      9 npm
      ISC
    • A
      license
      B
      quality
      B
      maintenance
      Enables reading public Bilibili video information — keyword search, UP profiles and uploads, video details and parts, comments and replies, danmaku, subtitles, and frame snapshots — through an MCP interface, with optional Bilibili login for authenticated features such as comments and subtitles.
      16
      170 PyPI
      3
      Apache 2.0