bilibili-skill

B 站 MCP Server + 按需加载技能包。通过 stdio 暴露 37 个工具，覆盖视频搜索/浏览/采集、评论/字幕/弹幕、动态/私信、收藏、视频投稿、本地表情包与绘画素材、操作审计。Claude Code、Cursor、Cline 等支持 stdio MCP 的客户端可以直接接入；读取 skill.json 的技能宿主（如 OpenClaw）可以按清单懒加载。

本项目与哔哩哔哩官方无关。自动化调用可能违反平台规则并带来账号风险，请遵守社区规则，仅用于学习研究。

目录

• 快速开始

• 登录

• 未登录能力边界

• 配置

• MCP 接入

• 工具表

• 技能包

• 安全与权限

• 日志

• 注意事项

• 许可证

Related MCP server: bilibili-mcp

快速开始

环境要求

• Python 3.10+：mcp_server.py 直接使用 X | None 联合类型注解。

• Windows / macOS / Linux。

• 依赖见 requirements.txt：

  依赖	用途
  bilibili-api-python>=17.0.0	B 站 API 客户端
  mcp>=1.0.0,<2	MCP Python SDK
  httpx>=0.27	HTTP 客户端
  aiohttp>=3.9.0	字幕下载等异步请求
  qrcode[pil]>=8.0	登录二维码
  Pillow>=10.0	图片处理
  av>=14.0.0	PyAV，视频抽帧/密集联系表
  python-dotenv>=1.0	可选依赖（启动器检查）

• ffmpeg：只有“投稿时没有提供封面、需要从视频自动截封面”时才需要，并且必须在 PATH 中。视频抽帧使用 PyAV（av 包），不需要系统安装 ffmpeg。

安装与自检

cd bilibili-skill
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

python -m pip install -r requirements.txt
python skills/bilibili/run_mcp.py --check

--check 只检查仓库根和依赖，不启动 Server。正常输出类似：

skill: .../skills/bilibili
python: .../python
root: .../bilibili-skill
server: .../bilibili-skill/mcp_server.py
missing: none

如果缺少可选依赖，会额外打印 optional-missing: ...；缺少必需依赖时退出码为 2，并给出安装命令。

启动

python skills/bilibili/run_mcp.py

也可以直接运行 python mcp_server.py。两者都使用 stdio；通常不需要手工启动，由 MCP 客户端拉起子进程。

测试

python -B -m unittest discover -s tests

测试覆盖工具清单一致性、未登录公开读取、上传/出站图片白名单、凭证续期、配置优先级、抽帧与雪碧图等。

登录

B 站的公开视频、评论、弹幕、用户资料等大多不需要登录；字幕、私有读取和所有写操作需要登录。

凭证保存在仓库根目录的 bili_credential.json（与 mcp_server.py 同级）。bili_credential.json*、qrcode_login.png、config.json、logs/ 都已被 .gitignore 忽略。

通过 AI 扫码

1. 让 AI 调用 bili_login。已登录且凭证有效时返回 already_logged_in；否则返回 qrcode_ready，其中包含 qrcode_image（data:image/png;base64,... 形式，可直接展示）、qrcode_file（qrcode_login.png 的绝对路径）和 qrcode_url。

2. 用 B 站 App 扫码，并在手机上确认。二维码 180 秒内有效。

3. 让 AI 调用 bili_login_check 查询状态：

   • waiting：等待扫码；

   • scanning：已扫码，等待手机确认；

   • done：登录成功，凭证已写入；

   • already_logged_in：当前已有凭证，没有进行中的扫码会话；

   • timeout / error：二维码过期或失败，重新调用 bili_login；

   • no_session：没有进行中的登录，先调用 bili_login。

4. 需要确认凭证是否仍有效时，调用 bili_check_credential。它使用需要登录态的接口验证；成功时返回 logged_in、uid、username，未登录或凭证失效时返回 logged_in: false 和原因。

终端扫码

python bili_login.py
# 等价于
python -m bili_auth

终端方式会在仓库根生成 qrcode_login.png，轮询 180 秒，成功后写入 bili_credential.json。Windows 下会尝试用系统看图工具打开；其他平台只打印文件路径。二维码在完成后删除。

凭证与自动续期

• 必需字段：sessdata、bili_jct、dedeuserid。任一项为空视为未登录。

• 续期字段：ac_time_value（refresh_token）；buvid3 会保留用于请求。

• 每次取凭证时按需刷新，检查间隔节流为 10 分钟：先问服务端是否需要刷新，需要才调用刷新接口。

• 刷新成功后用“临时文件 + 原子替换”写回，并保留文件里其它自定义字段；刷新失败不会阻塞调用，继续使用旧 cookie。

• 多个进程同时刷新时使用跨进程文件锁；如果发现另一个进程已经刷新过，直接复用文件里的新凭证。

• 没有 ac_time_value 时不会自动续期，只能重新扫码。

• 日志只记录刷新状态，不打印任何 cookie 值；POSIX 下凭证文件权限会被设为 0600（Windows 不设置）。

不要提交或分享 bili_credential.json。 它等同于账号登录态。

未登录能力边界

工具分两类取凭证：公开只读工具在未登录时使用空凭证；需要登录的工具会返回结构化的 login_required，而不是抛出 MCP 错误。

需要登录时，写工具通常返回：

{
  "success": false,
  "login_required": true,
  "error": "未登录B站！请先调用 bili_login 工具获取登录二维码，让用户扫码登录。"
}

bili_subtitle 的字幕接口强制要求 sessdata，未登录时返回：

{
  "bvid": "BV...",
  "title": "...",
  "login_required": true,
  "message": "读取字幕需要先登录 B 站。请用户明确要求后，再调用 bili_login 扫码。"
}

bili_user_info 未登录时仍返回昵称、等级、粉丝等公开字段，但 likes、archive_view、article_view 为 null，并带 stats_unavailable: true 和 stats_error，不会用 0 冒充“没有数据”。

未登录查别人的收藏夹时，B 站可能返回 data=null。bili_favorite_lists 会区分“未登录”和“对方没有公开收藏夹”：前者返回 login_required，不会伪装成空列表。

配置

取值优先级（只适用于通过 bili_config.py 读取的键）：

环境变量  >  仓库根目录的 config.json  >  代码默认值

config.json 与 mcp_server.py 同级，可选，由你手工创建或由外部工具写入；仓库不附带该文件。也可以用 BILI_CONFIG_PATH 指向别处。键名是扁平的，与下表中 bili_config 读取的键一致：

{
  "BILI_MAX_VIDEO_MINUTES": 60,
  "BILI_FRAMES_MAX": 3,
  "BILI_FRAMES_MAX_HEIGHT": 1080,
  "BILI_FRAMES_MAX_AGE_SECONDS": 3600,
  "BILI_DENSE_INTERVAL_SECONDS": 3.0,
  "BILI_DENSE_MAX_FRAMES": 40,
  "BILI_DENSE_HEIGHT": 480,
  "BILI_WINDOW_SECONDS": 120,
  "BILI_STORYBOARD_MAX_FRAMES": 24
}

环境变量

另外建议在 MCP 客户端配置里设置：

"PYTHONUTF8": "1",
"PYTHONIOENCODING": "utf-8"

注意：

• 仓库不会自动加载 .env。.env.example 只是参考，环境变量必须由启动 MCP Server 的进程或 MCP 客户端配置提供。

• 空环境变量视为未设置；非法数字会回落到默认值，不会让 Server 启动失败。

• 抽帧/雪碧图相关常量在模块导入时读取，修改后需要重启 Server（在技能宿主里就是重新激活技能）才生效。

• BILI_UPLOAD_DIR 的相对路径按仓库根解析；BILI_CONFIG_PATH、BILI_AVOID_PATH、BILI_MCP_LOG_DIR 直接按路径使用，相对路径会按进程当前目录解析，建议写绝对路径。

MCP 接入

Claude Code

在项目根目录创建 .mcp.json（该文件已被 .gitignore 忽略，避免提交本机路径）：

{
  "mcpServers": {
    "bilibili": {
      "command": "/path/to/bilibili-skill/.venv/Scripts/python.exe",
      "args": ["/path/to/bilibili-skill/skills/bilibili/run_mcp.py"],
      "env": {
        "BILI_SKILL_ROOT": "/path/to/bilibili-skill",
        "PYTHONUTF8": "1",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

把示例里的 /path/to/bilibili-skill 换成实际仓库绝对路径。Windows 的解释器是 .venv/Scripts/python.exe；macOS / Linux 通常是 .venv/bin/python，例如：

"command": "/Users/you/bilibili-skill/.venv/bin/python"

说明：

• 使用绝对路径；Windows 路径可以写成正斜杠，避免 JSON 转义。

• BILI_SKILL_ROOT 是可选的：run_mcp.py 会从技能目录向上查找 mcp_server.py；只有技能目录被单独复制时才必须设置。

• 修改 .mcp.json 后需要重载/重启客户端。

• 工具在 Claude Code 里通常带服务器前缀，例如 mcp__bilibili__bili_video_info，权限允许列表按这个形式写。

Cursor / Cline

两者都支持 stdio MCP。把上面的 mcpServers.bilibili 段放进客户端的 MCP 配置即可，command、args、env 保持完全一致：

• Cursor：设置中的 MCP Servers，或项目级 MCP 配置（位置随版本）；

• Cline：MCP Servers 配置面板/配置文件。

不同版本的位置和字段可能略有差异，以客户端当前版本为准。关键只有三点：用虚拟环境里的 Python、启动 skills/bilibili/run_mcp.py、设置 BILI_SKILL_ROOT 和 UTF-8 环境变量。

OpenClaw / 读取 skill.json 的宿主

这类宿主会读取 skills/bilibili/skill.json，按 mcp 段启动 Server：

• mcp.command：python；

• mcp.command_env：BILI_SKILL_PYTHON，把环境变量设成虚拟环境解释器；

• mcp.args：["run_mcp.py"]；

• mcp.cwd：.，即技能目录；

• transport：stdio。

把 skills/bilibili 注册为技能目录即可。activation.mode 是 lazy，空闲 10 分钟后卸载；patrol.enabled 默认 false。如果宿主把技能目录复制到别处，仍需把 BILI_SKILL_ROOT 指向包含 mcp_server.py 的仓库根，否则 run_mcp.py 会给出可读错误。

examples/component_smoke.py 是一个最小宿主示例：默认只读 skill.json 并打印描述，不启动 MCP；加 --call 才启动 stdio 子进程、列工具并调用一次：

python examples/component_smoke.py
python examples/component_smoke.py --call bili_sticker_list
python examples/component_smoke.py --call bili_search --args '{"keyword": "B站"}'

Pending approval 与无头模式

• 交互式客户端在首次使用项目级 .mcp.json 或首次调用 MCP 工具时，可能显示 Pending approval，需要在客户端里批准该服务器/工具。

• 无头/后台模式没有交互确认窗口，必须在启动前把所需工具加入客户端的允许列表或权限配置，否则调用会一直等待审批。

• MCP Server 本身没有办法自动批准，也不会绕过客户端的权限层。

Claude Code 与 skill.json

Claude Code 通过 MCP 协议加载工具，不会强制执行 skill.json 里的额度、白名单和审批策略。因此：

• skill.json 里的 tools.write / tools.human_only / tools.message 分类不会被 Claude Code 自动执行；

• 每日额度（评论 20、私信 10、动态 1）、白名单豁免、投稿审批、巡检都不会因为 skill.json 写了就自动生效；

• 需要在 Claude Code 的权限设置/允许工具列表里限制，或使用真正读取 skill.json 的宿主。

MCP Server 自身同样不执行这些策略，详见安全与权限。

工具表

所有工具都返回 JSON 字符串。常见字段：

• success：布尔值，部分只读工具直接返回数据，不带该字段；

• error / message：错误或说明；

• login_required：预期内的未登录状态，不会作为 MCP isError 抛出。

部分工具（如 bili_hot_buzzwords、bili_weekly_hot、bili_unread_messages、bili_received_replies）直接返回 B 站接口的原始 JSON，字段以接口为准。

共 37 个工具，与 tool_manifest.ALL_TOOL_NAMES 一致：write 6 个、read 28 个、human_only 3 个；其中 message 2 个，是 write 的子集。

登录与凭证（3）

浏览与采集（8）

补充：

• bili_video_overview 默认每约 3 秒一帧、最多 40 帧；没有 PyAV 或密集抽帧失败时退回 B 站雪碧图，最多 24 帧。传 start/end 时窗口默认最多 120 秒；不传则看全片。超过 BILI_MAX_VIDEO_MINUTES（默认 60 分钟）的视频直接拒绝。

• bili_video_frames 的 max_frames 默认 3 张，硬上限由 BILI_FRAMES_MAX 控制（默认 3，最大 9），传更大的值会被截断；依赖 PyAV，缺少时返回“未安装 PyAV，无法抽高清帧”。

• bili_crawl 未登录时评论仍会采集，每个视频的字幕部分会带 subtitle_error，值为登录提示。

互动与发布（5）

补充：

• bili_reply 只有 rpid=0（发新评论）时能带图；回复别人的评论不能带图。图片上限 5 MB。

• bili_send_dynamic / bili_send_opus 的图片只接受本地表情包或 data/drawn/ 产物，最多 9 张。

• bili_send_opus 会把标题放在正文首行（【标题】）；bilibili-api 17 没有专栏发布接口。

• 投稿标题会截到 80 字；tags 逗号分隔，空值回落为“视频”；tid 可用 bili_video_zones 查询。

• source 为空表示原创，no_reprint 默认 true；填写 source 表示转载，no_reprint 会被置为 false。

• video_path / video_paths 必须位于投稿白名单目录，默认 data/uploads/，可用 BILI_UPLOAD_DIR 覆盖。

• cover_path 只接受本地表情包或绘画产物；不填时用 ffmpeg 从视频第 3 秒（失败再试第 0 秒）截封面。

热门、排行与用户（8）

bili_rank 的 category 可取：all、original、rookie、douga、music、dance、game、knowledge、technology、sports、car、life、food、animal、fashion、ent、cinephile。

收藏夹（3）

bili_favorite 在 media_id=0 时会先查收藏夹列表，优先找标题为“默认收藏夹”的项，否则用第一个；账号没有任何收藏夹时返回错误。

私信、表情与通知（7）

补充：

• bili_send_message 的 text 和 image 至少要有一个；图片上限 8 MB；先发文字再发图片，图片失败时文字结果会保留在 sent 里。

• bili_send_sticker 直接接受表情名，可带或不带扩展名，大小写不敏感；不接受路径分隔符或 ..。

• bili_recent_messages 只返回有未读、最后一条不是自己发的、且不是系统通知的会话。

本地素材与日志（3）

补充：

• bili_self_image 读取 data/self/character.png（或 .jpg/.jpeg/.webp）和 data/self/character.md/character.txt。原图超过约 1.2 MB 时会生成 character.view.jpg 缩略图。

• bili_generate_image 的 width/height 会被夹到 512–1600；mood 支持 happy/calm/tired/excited，未知值回落 happy。当前 bili_draw.py 没有接入任何供应商，configured() 恒为 False，调用会返回失败原因，不会退回本地画图。

• bili_activity_log 自身不会被写入审计日志，避免每看一次日志就多一条噪音。

技能包

目录结构

skills/
├── README.md                       # 技能目录说明
└── bilibili/
    ├── SKILL.md                    # 技能入口（skill.json 的 entry）
    ├── skill.json                  # 技能清单：描述、激活、MCP 启动、工具分类、额度、巡检
    ├── run_mcp.py                  # 技能内 MCP 启动器，支持 --check
    ├── mcp.json.example            # 通用 MCP 客户端配置模板
    └── instructions/
        ├── persona.md              # 人设
        ├── rules.md                # 行为规则
        ├── tools.md                # 工具使用说明
        └── patrol.md               # 巡检说明

run_mcp.py 不假设宿主从哪个目录启动：优先使用 BILI_SKILL_ROOT，否则从技能目录向上查找 mcp_server.py。技能目录被单独复制、找不到 Server 时会给出可读错误，而不是只让宿主看到 Connection closed。

skill.json 的关键内容

这些额度、白名单、投稿审批和巡检都是宿主契约。MCP Server 不读取 skill.json，也不会自动执行。

不同宿主至少需要哪些文件

只复制 skills/bilibili 目录而不带仓库根代码是跑不起来的：run_mcp.py 需要找到 mcp_server.py。测试里也覆盖了这种错误提示。

安全与权限

MCP Server 本身不执行以下策略：

• 每日额度（评论、私信、动态）；

• 白名单豁免；

• human_only 投稿审批；

• 巡检调度。

这些只写在 skill.json 里，limits.enforced_by 明确是 host。任何能调用 MCP 工具的客户端都可以调用写工具和投稿工具；human_only 只是给宿主的元数据，不是 Server 侧的强制拦截。要限制，必须在宿主、客户端权限或自己的封装层实现。

Server 侧实际执行的技术保护：

• 登录检查：需要登录的工具在本地没有凭证时返回结构化 login_required，不会继续调用 B 站写接口。

• 投稿目录白名单：bili_upload_video / bili_upload_video_multi 只接受 data/uploads/（或 BILI_UPLOAD_DIR）内的已存在文件。这个检查只判断路径，不检查扩展名或内容。

• 出站图片白名单：评论配图、动态/图文图片、私信图片、视频封面只能来自 data/self/stickers/ 或 data/drawn/；网络图片、其他本地目录、路径穿越都会被拒绝。

• 超长视频保护：bili_video_overview / bili_video_frames 对超过 BILI_MAX_VIDEO_MINUTES（默认 60 分钟）的视频直接拒绝。

• 评论冷处理名单：bili_reply 读取 data/agent.avoid.json；命中楼层或 UP 主时拒绝回复。名单只增不减，想解禁直接编辑该文件删掉条目，下次读取生效，不需要重启。

• 凭证本地化：凭证、日志、配置都只保存在本地，且默认被 .gitignore 忽略。

巡检默认关闭（patrol.enabled: false），Server 没有内置定时器；需要巡检时由宿主按 skill.json 的 patrol 段调度。

其他风险：

• 本项目与 B 站官方无关，使用的是非官方接口；接口可能变化、限流或触发风控（如 -412）。

• 自动化评论、私信、投稿可能违反社区规则，导致账号受限。请控制频率，不要批量骚扰。

• 不要把 bili_credential.json、日志或包含个人内容的配置提交到公开仓库。

日志

默认日志目录是仓库根目录的 logs/，可用 BILI_MCP_LOG_DIR 覆盖。每个自然日生成两个文件：

logs/activity-YYYY-MM-DD.jsonl   # 一行一条 JSON，机器可读
logs/activity-YYYY-MM-DD.md      # 按会话分组的 Markdown，人可读

每次工具调用（bili_activity_log 自身除外）都会记录：

日志写入失败会被吞掉，绝不影响工具调用。Markdown 版按会话分组，结果预览更短。

查看日志：

python bili_log.py                  # 今天的最近 30 条
python bili_log.py -n 100           # 今天最近 100 条
python bili_log.py --writes         # 只看写入操作
python bili_log.py --tool bili_reply
python bili_log.py --summary        # 今天的操作统计
python bili_log.py --date 2026-10-22
python bili_log.py --list           # 有哪些天的日志

也可以让 AI 调用 bili_activity_log：

{"count": 20, "date": "", "tool": "", "writes_only": false}

date 留空或 today 表示今天，也接受 yesterday 和 YYYY-MM-DD；count 最大 200。

日志可能包含隐私内容：参数和结果里可能出现评论正文、私信内容、UID、图片路径等。请只保存在本地，不要公开分享或提交。logs/ 已在 .gitignore 中。

注意事项

• 本地文件：bili_credential.json、config.json、logs/、data/ 下的运行素材都只应保存在本地。凭证等同于账号登录态，不要提交或发给他人。

• 出站图片：只允许本地表情包（data/self/stickers/）和绘画 AI 产物（data/drawn/），格式限 png/jpg/jpeg/webp，拒绝网络图片。评论配图上限 5 MB，私信图片上限 8 MB；动态/图文/封面不额外检查 MB 数，只校验来源和格式。

• 表情包管理：

  python bili_stickers.py list
  python bili_stickers.py add 图片路径 表情名 [--size 512] [--force]

  会把图片裁成正方形、默认缩放到 512×512 并保存为 PNG；超过 8 MB 时会警告“B站私信可能发不出去”。

• 投稿目录：默认 data/uploads/，目录不存在时先创建并把视频放进去，或设置 BILI_UPLOAD_DIR。只允许上传该目录内的文件。没有提供封面时会调用系统 ffmpeg 自动截帧；ffmpeg 不可用会导致投稿失败。

• 绘画 AI 未配置：bili_draw.configured() 当前恒为 False，bili_generate_image 会返回 success: false 和“绘画 AI 还没接入”的原因；没有本地画图兜底。需要生成图片时，先按 bili_draw.py 的接口接入供应商，并确保产物保存到 data/drawn/。

• 视频长度限制：bili_video_overview 和 bili_video_frames 只处理不超过 BILI_MAX_VIDEO_MINUTES（默认 60 分钟）的视频；上传视频不受这个限制。

• 临时文件：联系表和抽帧会写到 data/tmp/storyboard/、data/tmp/frames/；bili_video_frames 的结果和 bili_video_overview 的 storyboard 段会带 cleanup_id 和 expires_in_seconds。下次运行时会清理过期目录（帧默认 3600 秒，雪碧图 3600 秒）；目前没有单独的 MCP 清理工具。

• 接口稳定性：B 站接口和风控策略可能变化，bilibili-api 版本升级也可能改变字段。出现异常时先看日志和 bili_check_credential 的结果。

• 合规使用：遵守 B 站社区规则和当地法律；不要用自动化做垃圾评论、骚扰私信、刷量或未授权投稿。仅用于学习研究。

许可证

本项目自身使用 MIT License，见 LICENSE。Copyright (c) 2026 bilibili-skill contributors。

第三方依赖及许可证（以实际安装版本为准，发布前请用 pip show <包名> 或上游 LICENSE 核实）：

如果 bilibili-api-python 实际为 GPL-3.0，分发包含它的组合作品可能需要遵守 GPL-3.0；仅保留 MIT 可能不够。详见 THIRD_PARTY_NOTICES.md。