bilibili-learning-mcp
Provides tools for interacting with Bilibili learning videos: searching videos, retrieving video metadata, fetching subtitles with timestamps and optional time-range extraction, and reading hot comments for reputation or feedback.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bilibili-learning-mcp 帮我找「线性代数 期末速成」播放量最高的视频,并整理带时间戳的字幕笔记"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
# bilibili-learning-mcp
让 Codex、Claude Desktop 等 MCP 客户端直接「看」B 站学习视频的 server: 搜索视频、读取简介、抓取字幕、查看热门评论。
只提供数据,不调用任何 LLM API。 总结、笔记、问答全部由客户端模型完成; Server 不含任何模型调用、不下载视频、不持久化内容。
状态:0.1.0(Alpha),当前仅支持 stdio 传输。
它能做什么
工具 | 作用 | 登录 Cookie |
| 关键词搜索,返回标题 / UP主 / BV号 / 时长 / 播放量 | ⚪ 可选 |
| 标题、简介、UP主、分P(含 cid)、播放/点赞/收藏、时长 | ❌ 不需要 |
| 字幕逐行输出 | ⚠️ 通常需要 |
| 按点赞排序的热门评论,用来判断视频口碑 | ❌ 不需要 |
搜索、视频信息、热门评论均可匿名使用;字幕(尤其 AI 字幕)需要登录 Cookie。 配置 Cookie 还能降低搜索触发风控的概率。
典型用法:
帮我找「线性代数 期末速成」的视频,挑播放量最高的那个,读字幕整理一份带时间戳的笔记。
Related MCP server: bilibili-info-mcp
快速开始
1. 准备环境
Python 3.10+
可选:Node.js 18+(仅使用 MCP Inspector 调试时需要)
2. 安装
git clone https://github.com/Unc1e-2ack/bilibili-learning-mcp.git
cd bilibili-learning-mcp
uv sync3. 接入客户端
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-mcpWindows 下路径建议用绝对路径并加引号(例如 "G:\path\to\bilibili-learning-mcp")。
注册后新开一个会话才会生效。
其它 MCP 客户端
stdio 命令:
uv --directory /path/to/bilibili-learning-mcp run bilibili-learning-mcp4. 可选:配置 Cookie(字幕需要)
浏览器登录 bilibili.com;
按
F12打开开发者工具 → Network,筛选api.bilibili.com;随便点一个请求,复制请求头里完整的
Cookie:值(至少包含SESSDATA);复制配置模板并填入:
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 | 提示 |
匿名搜索被 412 / 风控拦截 | 提示配置 Cookie 后重试 |
| 提示重新获取 Cookie |
| 提示稍后重试,持续失败则更新 Cookie |
网络超时(10s) | 提示稍后重试 |
返回非 JSON | 说明可能被风控页拦截 |
无字幕 | 提示改用 |
设计说明
匿名优先,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贡献与安全
提交规范、开发约定见 CONTRIBUTING.md
漏洞报告方式见 SECURITY.md
版本变更见 CHANGELOG.md
合规与免责
本项目仅调用 B 站公开 Web 接口,用于个人学习与内容检索;
请遵守 B 站用户协议 与
robots.txt,不要高频抓取;字幕与评论版权归原作者所有,请勿二次分发;
本项目与哔哩哔哩官方无关。
License
Available Tools
4 toolsget_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
Scored across 4 tools
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'.
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.
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.
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
Related MCP Connectors
Bilibili videos for AI agents: search, creators, trending, stats, tags and danmaku comments.
Bilibili (B站) data without login: video stats, comments, danmaku, creators, trending, hot searches.
An MCP server that gives any LLM or agent clean YouTube transcripts on demand: a single video, a whole channel, or a playlist, plus AI cleanup of auto-generated captions. API-key auth, credit-based, same backend as the public v1 API. Get a free API key with 25 free credits at youtubetranscriptdownload.com/account.
Real-time YouTube transcripts, comments, channels & video search MCP. Local npx or hosted OAuth.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server powered by public Bilibili APIs so AI agents can search videos and read public video and creator metadata.MIT
- AlicenseAqualityDmaintenanceMCP server for fetching Bilibili video metadata and subtitles. Supports running locally via stdio transport for integration with MCP clients like Cursor or Claude Desktop.19 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables retrieving Bilibili video metadata, part lists, and timestamped official/AI subtitle transcripts through MCP tools, without downloading videos.MIT
- AlicenseBqualityBmaintenanceEnables 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.16170 PyPI3Apache 2.0