Skip to main content
Glama
bili-material-mcp
by sac432
README.md
# bili-material-mcp | 只读、省 token 的 B站素材 MCP

中文 | [English](README.en.md)

> **先看三行**
> - 给写作 agent 用的 B站素材源:**搜视频、读字幕、读热评**,返回紧凑纯文本。
> - **只读**:代码里根本没有发评论、私信、点赞、关注这类功能,不会用你的账号说任何话。
> - **省 token**:在 dsh 里总结 3 个视频只需要 2 步、约 50K token,dsh-bili-scroll 做同样的事用了约 217K([实测数据](docs/BENCHMARK.md))。

非官方项目,与哔哩哔哩无关。仅供个人学习、研究和写作参考。

## 它做什么

- `search_videos`:按关键词搜视频,每个视频一行(BV 号、标题、UP主、播放/点赞/评论、时长、日期)
- `get_video_digests`:**一次调用**读完最多 5 个视频的信息、**完整字幕**和热评,agent 只需要一步
- `get_video_digest` / `get_subtitle` / `get_hot_comments`:只看一个视频、分段读字幕、只读评论时使用

字幕会去掉时间戳、合并短句;评论会去掉表情码、重复和过短的内容。同一个视频读第二遍走本地缓存,不再请求 B站。

## 安装

需要 Python 3.10+。

```powershell
git clone https://github.com/sac432/bili-material-mcp.git
cd bili-material-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```

## 登录(读字幕需要)

```powershell
.\.venv\Scripts\python.exe -X utf8 -m bili_material.login
```

用 B站 App 扫终端里的二维码;看不清的话,打开 `data/login_qrcode.png` 扫。凭据只保存在本机的 `data/credential.json`,不会上传。

> ⚠️ **请用小号。** 虽然是只读访问并且做了限速,自动化访问仍然可能触发风控。

不登录也能搜索和看视频信息,但读不到字幕,热评也只有大约 3 条。

## 接入(如果你有使用agent,直接把链接发给它就好了)

**Claude Code**:把 `.mcp.json.example` 复制成你项目里的 `.mcp.json`,把 `<install-dir>` 改成本仓库所在的目录。

**DeepSeek Harness(dsh)**:在 `~/.dsh/profiles/web/cordis.patch.yml` 里加入下面这段,然后重启 dsh:

```yaml
- insert:
    - id: mcp-bili-material
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: bili-material
        transport: stdio
        command: '<install-dir>/.venv/Scripts/python.exe'
        args: ['-X', 'utf8', '-m', 'bili_material.mcp_server']
        cwd: '<install-dir>'
        toolCallTimeoutMs: 90000
```

它是标准的 MCP server,其他 MCP 客户端也能用。写代码时也可以跳过 MCP,直接 `from bili_material import BiliMaterial` 拿到 dict。

## 红线

- 只注册读取类工具,没有任何写操作的代码路径,也没有开关可以打开
- 所有请求排队发送,间隔至少 1.2 秒;遇到风控就退避重试,不做全站抓取
- 凭据只保存在本机,`data/` 已经加进 `.gitignore`

## 它是怎么省 token 的

agent 每走一步,都要把系统提示、工具说明和之前所有结果重新发一遍,所以**步数比单次返回的大小更费钱**。本项目的做法:

1. 一次调用就把多个视频的信息、字幕和评论都拿回来,不让 agent 一个接一个地调;
2. 直接给完整字幕,省掉回头补读的那一步;
3. 输出用纯文本,只保留有用的字段,不用 JSON。

## 装不上 / 用不了

- **读不到字幕**:先运行 `python -m bili_material.login --check` 检查登录状态;另外,有些视频本身就没有字幕。
- **报 curl error 77**:安装路径里有中文时,库默认的 curl_cffi 会出这个错。本项目已经改用 aiohttp;如果还遇到,请提 issue。
- **扫码后提示没有 SESSDATA**:二维码过期,或者在手机上取消了登录,重新扫一次即可。

## 如果你是 AI 助手,正在帮用户装这个项目

1. 确认用户的电脑上有 Python 3.10+;
2. 按「装」一节建好 venv 并安装;
3. 让**用户自己**扫码登录,并提醒他们使用小号;
4. 按用户使用的客户端写好配置,把 `<install-dir>` 替换成实际路径,然后提醒用户重启客户端。

## 许可证

GPL-3.0-or-later,因为依赖的 [bilibili-api-python](https://github.com/Nemo2011/bilibili-api) 是 GPL-3.0-or-later。参考过 adoresever/bilibili-mcp 和 c1overzz/dsh-bili-scroll(均为 MIT 许可证)的接口用法,没有复制它们的代码。

获取的字幕和评论版权归原作者所有。请只把它们当作学习用途,引用时适量并注明出处。

TDQS

A3.9/5.0

Scored across 5 tools

Disambiguation3/5

get_video_digest and get_video_digests differ only by a plural 's' and perform near-identical work at different scales, which is a classic misselection trap despite the descriptions explaining the batch preference. The digest tools also overlap with get_subtitle and get_hot_comments, since the digest already embeds a compressed subtitle and top comments; the descriptions do clarify when to use each, but boundaries are softer than ideal.

Naming Consistency4/5

All names are snake_case with a predictable verb_noun shape (search_videos, get_subtitle, get_hot_comments). The only blemish is the singular/plural pair get_video_digest / get_video_digests, which is consistent in form but makes the two names visually confusable.

Tool Count4/5

Five tools is a tight, well-scoped set for fetching Bilibili video material, with each tool mapping to a concrete retrieval need. It is on the lean side, but nothing feels padded or redundant enough to warrant a lower score.

Completeness4/5

The surface covers search, single and batch digest, chunked subtitle reading, and comment retrieval, which are the core read workflows for video material collection. Gaps exist around uploader/author lookup, related or recommended videos, and paged search results beyond the 20-item cap, but these are workaroundable rather than blocking.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues