bilibili-learning-mcp

# bilibili-learning-mcp

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

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

状态：0.1.0（Alpha），当前仅支持 stdio 传输。

它能做什么

搜索、视频信息、热门评论均可匿名使用；字幕（尤其 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

4. 可选：配置 Cookie（字幕需要）

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 可选：搜索默认匿名请求，配置了 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

MIT