bili-open-mcp — 哔哩哔哩 / B站 MCP Server#

关键词：哔哩哔哩 MCP · B站 MCP · bilibili MCP · bilibili MCP server · 哔哩哔哩开放平台 · bilibili open platform API · Model Context Protocol · MCP 工具 · AI 调用 B 站接口

记这个就行：bili-open-mcp —— 一个让 AI 直接检索、直接调用哔哩哔哩开放平台的 MCP 服务。

哔哩哔哩开放平台（https://open.bilibili.com/doc/4）的 MCP 服务 + 结构化接口库 + 可运行示例。把 170 篇文档变成 AI 能直接检索、直接调用、直接生成签名的东西。

你想要	看哪
在浏览器里搜着看	在线文档站 —— 271 个页面，接口 / 隐藏能力 / 指南 / 事件 / 错误码全文搜索
怎么装、怎么接、每个工具怎么用	USAGE.md —— 完整操作手册，含真实输出样例与排查表
我这点凭据能用哪些功能	USAGE.md §0 —— 一张表说清
给 AI 读的使用契约	AGENTS.md
接口来源 / 能力边界 / 免责声明	DISCLAIMER.md

常见搜法都能到这里：哔哩哔哩 mcp、B站 mcp server、bilibili mcp、 b站开放平台 mcp、用 AI 调 B 站接口、bilibili open platform api mcp。

❗

重要

本项目调用的所有接口均为哔哩哔哩官方公开提供的接口（开放平台文档 / 开放平台域名 / 主站 Web 接口 / 官方直播间长连协议），不含私有接口或绕过鉴权的实现。详见 DISCLAIMER.md。

凭据需自备，且缺失时功能受限：没有 BILI_COOKIE_FILE（→ secrets/cookies.json）和 BILI_CRED_FILE（→ secrets/open-platform.json），则开放平台接口与主站 Web 接口全部不可用，只剩文档检索、错误码查询、代码生成、沙盒 mock、签名演示这些纯本地能力。本项目不内置任何凭据，两个文件所在目录已在 .gitignore 中排除。

第三方项目，与哔哩哔哩无隶属或背书关系。请遵守官方协议并自行控制频率。

text

bili-open-mcp/
├─ USAGE.md            详细使用方法：19 个工具 + 端到端工作流 + 报错排查
├─ AGENTS.md           给 AI 的使用契约（详细版）
├─ DISCLAIMER.md       接口来源 / 凭据边界 / 使用者责任 / 责任限制
├─ LICENSE             MIT
├─ src/
│  ├─ server.mjs        MCP 服务（stdio，19 个工具 + 2 资源 + 1 提示）
│  ├─ signer.mjs        2.0 签名（HMAC-SHA256）
│  ├─ client.mjs        带签名的 HTTP 调用
│  ├─ codegen.mjs       6 种语言的调用代码生成
│  ├─ cookies.mjs       主站 Cookie 罐（EditThisCookie 导入 / 域匹配 / 脱敏）
│  ├─ credentials.mjs   开放平台凭据（参数 → 环境变量 → 文件）
│  ├─ paths.mjs         凭据文件路径解析（包目录优先，不受启动方 cwd 影响）
│  ├─ wbi.mjs           wbi 签名（mixin_key / w_rid）
│  └─ knowledge.mjs     速查 / OAuth / 长连协议 / Webhook 知识块
├─ secrets/             整个目录提交时排除（.gitignore）
│  ├─ cookies.json      主站 Cookie        ← BILI_COOKIE_FILE
│  └─ open-platform.json 开放平台凭据      ← BILI_CRED_FILE
├─ scripts/
│  ├─ build-spec.mjs    Markdown → data/*.json / llms.txt
│  ├─ build-site.mjs    data/*.json → docs/ 静态文档站（含隐藏能力 112 页）
│  ├─ check-site.mjs    站点自检：死链 / 锚点 / 资源 / 模板残留 / 混合内容
│  ├─ probe-web.mjs     主站隐藏能力可复现核验（逐条实打，核对实测状态）
│  ├─ audit.mjs         数据与文档一致性检查
│  ├─ selftest.mjs      工具 / 资源 / 提示 + 生成代码编译自检
│  ├─ check-project-config.mjs  按 opencode 项目配置实际拉起服务验证
│  └─ oauth-login.mjs   本机一键跑完 OAuth2 授权回环（npm run login）
├─ data/
│  ├─ index.json        170 篇文档的结构化规格（100 个端点）
│  ├─ llms.txt          紧凑清单，给 AI 一次性读
│  ├─ status-codes.json 118 个错误码
│  ├─ mock.json         43 个沙盒 mock 接口
│  └─ web.json          112 个主站 Web 隐藏能力（举报 / 拉黑 / 动态 / 评论 / 弹幕 / 直播 …）
└─ examples/
   ├─ bili_open.py      零依赖 Python 客户端（签名/请求/OAuth2/上传）
   ├─ video_upload.py   视频投稿全流程
   ├─ live_ws.py        直播间长连（WebSocket + 自定义二进制协议）
   ├─ node_client.mjs   Node 客户端
   ├─ sign_curl.sh      bash + openssl 签名
   └─ mcp-config.md     Claude / Cursor / Codex / OpenCode 接入配置

快速开始#

bash

cd C:/path/to/bili-open-mcp
npm install
npm run build        # 重新解析 170 篇文档
npm run audit        # 11 类一致性检查 → AUDIT PASSED
npm run selftest     # 工具 + 资源 + 提示 + 生成代码编译 → ALL SELFTEST PASSED
npm run check-config # 用 opencode 项目配置里的命令实际拉起服务

接入客户端见 examples/mcp-config.md。

工具一览（19 个）#

开放平台（签名 / OAuth2）#

工具	作用	典型输入
`bili_quickstart`	主机 / OAuth2 / 签名 / 错误码分段 / 沙盒一次讲清	`{}`
`bili_docs_search`	170 篇全文检索	`{"query":"投稿"}`
`bili_docs_list`	按目录或类型列文档	`{"folder":"直播能力"}`
`bili_docs_get`	读某篇完整 Markdown	`{"ref":"44"}`
`bili_endpoints`	按 method/scope/host/关键词过滤端点；`source:"web"` 列主站隐藏能力	`{"scope":"SHOP_ORDER_INFO","method":"POST"}`
`bili_scopes`	权限点 ↔ 端点映射	`{"scope":"ARC_BASE"}`
`bili_api_spec`	结构化接口规格（参数/必填/响应/子结构）	`{"ref":"12"}`
`bili_api_prepare`	参数类型转换 + 必填校验 + 多余字段检查	`{"ref":"12","body":{...}}`
`bili_codegen`	生成调用代码（python/node/curl/java/php/go）	`{"ref":"12","lang":"python"}`
`bili_api_sign`	生成签名头 + 可粘贴 curl	`{"url":"...","body":{...}}`
`bili_api_call`	真调接口（或 `dryRun:true` 只看请求）	`{"ref":"5"}`
`bili_oauth`	授权链接 / code 换 token / refresh 续期 / 凭据体检	`{"action":"authorize-url","gourl":"..."}`
`bili_upload_plan`	投稿分片计划（片数、offset、调用顺序）	`{"fileSizeMB":250}`
`bili_webhook`	41 个推送事件 + 验签代码	`{"action":"verify-code","lang":"python"}`
`bili_ws_protocol`	直播长连协议 + 客户端骨架	`{"code":"python"}`
`bili_mock`	沙盒 mock 换算与调用	`{"action":"map","ref":"12"}`
`bili_error_lookup`	错误码含义 / 前缀批量	`{"code":"1270","fuzzy":true}`

主站走 Cookie，不走 2.0 签名，两套体系互不通用。

工具	作用	典型输入
`bili_cookie`	Cookie 罐：状态 / 登录态体检 / 导入 / 设置 / 导出	`{"action":"whoami"}`
`bili_web_call`	带 Cookie 调 `*.bilibili.com` Web 接口，POST 自动补 csrf，`/wbi/` 自动签名	`{"path":"x/web-interface/nav"}`

wbi 签名#

2023 起 /x/space/wbi/*、/x/polymer/*、/x/v2/reply/wbi/* 这些要 wbi 签名。 bili_web_call 按路径自动判断（wbi:true/false 可强制），做的是：

从 /x/web-interface/nav 的 data.wbi_img 取 img_key / sub_key
按固定重排表拼出 32 位 mixin_key
参数按字典序 → 去掉 !'()* → urlencode → 末尾接 mixin_key → md5 = w_rid
请求带上 wts + w_rid

实测：/x/space/wbi/acc/info?mid=<uid> 带签名 code:0，wbi:false 则 -403 访问权限不足。

顺带一个坑：/x/space/wbi/arc/search（投稿列表）现在直接 -403，补 dm_img_list/dm_img_str/dm_img_inter 三件套也没用；旧路径 /x/space/arc/search 仍然 code:0 可用。

隐藏能力（开放平台文档里没有的那些）#

开放平台只放已商务合作的能力（文档自己写着「其它需求请发邮件咨询」，见 170_文档中未列出的功能）。剩下那一大片 —— 举报、拉黑、动态、评论、收藏、历史、消息、直播、创作中心 —— 都在主站 www/api.bilibili.com 与 api.live.bilibili.com 上，走浏览器 Cookie，不走 2.0 签名。

全部收进了 data/web.json：112 条 / 17 组，每条带方法、完整地址、参数、返回码、坑位与无 Cookie 实测状态。三种读法：

想要	怎么做
在浏览器里翻	在线文档站的「隐藏能力」页（112 个详情页）
让 AI 过滤	`bili_endpoints { "source": "web" }`、`{ "source": "web", "pathContains": "举报" }`、`{ "source": "all" }`
整块喂给 AI	resource `bili://web`
核对是否失效	`npm run web:probe` —— 按声明的参数重新打一遍，逐条比对预期

组一览：举报 3 · 账号与登录态 9 · 用户与空间 9 · 视频与播放 14 · 写操作 10 · 评论 6 · 动态 3 · 弹幕 6 · 关系与消息 9 · 私信 4 · 收藏/历史/稍后再看 8 · 合集与系列 3 · 搜索 4 · 直播 14 · 番剧与影视 3 · 创作中心 3 · 签名与风控工具箱 4。

举报#

两个入口，别混：

报什么	接口	关键参数
用户（资料/稿件/评论/动态/私信/专栏）	`POST /x/space/report`	`mid` + `reason` + `scene` + `tag_version`
单条评论	`POST /x/v2/reply/report`	`type` + `oid` + `rpid` + `reason`

/x/space/report —— 按 mid 举报，body 是 urlencoded，csrf 自动带：

json

{ "mid": 3546657551551003, "reason": 5, "scene": 1, "tag_version": 1 }

scene 与 reason 的合法组合由 GET /x/space/report/options 决定（以它返回的为准，别写死）：

reason	含义	可用 scene
5	传播色情/赌博/垃圾广告资源、诱导交易	1,2,3,4,5,6,7
1	色情低俗	1,2,3,4,5,6,7
4	引战、人身攻击	1,2,3,4,5,6,7
3	违法违禁行为	1
2	虚假不实信息	1

scene	含义
1	用户资料（头像、签名、昵称）
2	稿件
3	评论
4	动态
5	私信
6	专栏
7	其他（收藏夹、播单等）

tag_version 也取自 /options（当前为 1）。

前端（space.bilibili.com 的 index-*.js）里就是这么调的：

IC = ({mid, scene, reason, specific_reason, specific_reason_v2, tag_version}) =>
  Re.request({ url: "/x/space/report", method: "POST",
    headers: {"Content-Type": "application/x-www-form-urlencoded"},
    data: {mid, reason, scene, specific_reason, specific_reason_v2, tag_version} })

specific_reason / specific_reason_v2 没值时 axios 会丢掉，所以最小 body 是 mid=<uid>&reason=<一位数>&scene=<一位数>&csrf=<32> —— 实测 75 字节。

/x/v2/reply/report —— 报单条评论，需要 oid（稿件 aid）+ rpid：

text

reason: 0其他 1垃圾广告 2色情 3刷屏 4引战 5剧透 6政治 7人身攻击 8内容不相关 9违法违规
        10低俗 11非法网站 12赌博诈骗 13传播不实信息 14怂恿教唆 15侵犯隐私 16抢楼 17青少年不良

返回 12008 已举报过 / 12019 举报过于频繁 / -509 请求过于频繁 / -111 csrf 失败。注意这个接口风控更紧，静默调用常见 -352。

拿 oid/rpid 的路子（都已实测）：

要什么	调用
某人的动态列表	`/x/polymer/web-dynamic/v1/feed/space?host_mid=<uid>`（wbi）→ `id_str`
动态正文	`/x/polymer/web-dynamic/v1/detail?id=<id_str>`（wbi）
某人的投稿	`/x/space/arc/search?mid=<uid>&ps=20&pn=1`（旧路径，可用）→ `aid`/`bvid`
稿件评论区	`/x/v2/reply/wbi/main?oid=<aid>&type=1&mode=3`（wbi）→ `rpid`

Cookie 存在 secrets/cookies.json（已在 .gitignore 里），路径可用 BILI_COOKIE_FILE 覆盖；也可以直接 BILI_COOKIE="SESSDATA=…; bili_jct=…" 用环境变量注入。 SESSDATA 是账号凭证，工具默认脱敏输出，reveal:true 才显示原值。

两套凭据，别混#

	开放平台	主站 Web
用什么	`client_id` + `app_secret` + `access_token`	浏览器 `Cookie`（`SESSDATA`/`bili_jct`）
从哪来	open.bilibili.com 控制台 → 应用管理（需实名 + 开发者入驻）	浏览器里登录 bilibili.com 后导出 cookie
认证方式	HMAC-SHA256 签名（`x-bili-*` 头）	直接带 `Cookie` 头
存哪	`secrets/open-platform.json`（`BILI_CRED_FILE`）	`secrets/cookies.json`（`BILI_COOKIE_FILE`）
工具	`bili_api_*` / `bili_oauth` / `bili_upload_plan` …	`bili_cookie` / `bili_web_call`

Cookie 里没有 client_id / app_secret / access_token —— 这三个不是 cookie，任何 cookie 导出都拿不到。反过来，SESSDATA 也换不来开放平台的 access_token。两边不能互填。

补上开放平台凭据#

bash

# 1. 去 open.bilibili.com 登录 → 实名认证 → 开发者入驻 → 应用管理 → 创建「网页应用」
#    授权回调域 填 http://127.0.0.1:8848/callback
# 2. 一键跑完授权回环（自动抓 code、换 token、写入 secrets/open-platform.json）
cd C:/path/to/bili-open-mcp
npm run login -- --client-id <ClientID> --secret <Secret>

跑完 bili_api_call {ref:"#5"} 就能发真实请求了。

凭据解析顺序：显式参数 → 环境变量 → secrets/open-platform.json。用 bili_oauth {action:"status"} 可以看清每一格到底有没有、从哪来。

授权页 URL 格式（来自「接入指引 / 网页应用接入」，2025-03 新版页面）：

text

https://account.bilibili.com/pc/account-pc/auth/oauth?client_id=<ClientID>&gourl=<urlencoded 回调地址>&state=<随机串>

gourl 与应用里配的「授权回调域」不一致会报「不合法的授权请求」。 bili_oauth {action:"authorize-url", gourl:"…"} 会自动拼好并编码。

ref 接受 #12、12、012、文档 uuid、标题片段、接口 URL。

资源与提示#

类型	名称	内容
resource	`bili://catalog`	170 篇压成的一页纸清单（llms.txt）
resource	`bili://doc/{ref}`	单篇文档原文 Markdown
resource	`bili://web`	112 个主站 Web 隐藏能力目录（举报 / 拉黑 / 动态 / 评论 / 弹幕 / 直播 …），带无 Cookie 实测状态
prompt	`integrate-bili-api`	按开放平台规范生成接入任务说明（参数 `ref`）

凭据#

环境变量	说明
`BILI_CLIENT_ID`	client_id（= `x-bili-accesskeyid`），别名 `BILI_ACCESS_KEY_ID`
`BILI_APP_SECRET`	app_secret，别名 `BILI_SECRET`
`BILI_ACCESS_TOKEN`	OAuth2 access_token，别名 `BILI_TOKEN`
`BILI_COOKIE_FILE`	主站 Cookie jar 路径（覆盖默认解析）
`BILI_CRED_FILE`	开放平台凭据文件路径（覆盖默认解析）
`BILI_COOKIE`	直接给 Cookie 字符串，不落盘

凭据文件放在哪：secrets/cookies.json 与 secrets/open-platform.json 按 显式参数 → 环境变量 → 包目录 → 启动方 cwd 的顺序解析，写入固定落在包目录。放包目录下的 secrets/ 最稳 —— MCP 客户端是用它自己的项目目录当 cwd 拉起服务的，只按 cwd 找会一直显示「文件不存在」。要放别处就给 BILI_COOKIE_FILE / BILI_CRED_FILE 绝对路径。

无凭据时文档类工具照常工作，bili_api_sign 会用占位值演示签名结构， bili_api_call {dryRun:true} 能看完整请求。完整的能力对照表见 USAGE.md §0。

数据从哪来#

data/ 由 scripts/build-spec.mjs 从同级目录（文档 Markdown 所在目录）的 Markdown 生成。文档本身来自开放平台的目录接口：

text

GET https://open.bilibili.com/arcopen/user/open-doc/view?id=4

data.online_doc 是整棵目录树，每个 Article 节点带 md_url。文档更新后重跑：

bash

npm run build

统计#

文档 170 篇：95 篇单接口 + 2 篇多接口（共 100 个端点）、41 个推送事件、30 篇指南、2 篇协议说明
主站 Web 隐藏能力 112 条 / 17 组（data/web.json），90 条 GET 可由 npm run web:probe 复现核验
1243 个参数对象，100% 带类型；359/364 个请求参数带「必传」标记
20 个 scope、118 个错误码

面向 AI 的完整使用契约见 AGENTS.md。数据一致性由 npm run audit 把关（11 类检查）。

注意#

所有业务接口在 https://member.bilibili.com，OAuth 在 https://api.bilibili.com。
上传分片走 https://openupos.bilivideo.com，裸二进制、不带签名头，凭 url 上的 upload_token 鉴权。
稿件删除不可逆。

免责声明（摘要）#

使用前请读全文：DISCLAIMER.md。 共 15 条，要点：

接口来源：本项目调用的所有接口均为哔哩哔哩官方提供并公开的接口 （开放平台文档 / 官方业务域名 / 官方 OAuth2 / 官方上传域名 / 官方直播间长连协议 / 官方 Webhook 规范）， 不含私有接口、破解接口或绕过鉴权的实现。
无隶属关系：第三方项目，与哔哩哔哩（上海幻电信息科技有限公司 / 上海宽娱数码科技有限公司）没有隶属、赞助、合作或背书关系；相关名称与商标归其权利人所有。
凭据自备，缺失即功能受限：本项目不内置、不收集、不上传任何凭据。没有 BILI_COOKIE_FILE（secrets/cookies.json）和 BILI_CRED_FILE（secrets/open-platform.json），则开放平台接口与主站 Web 接口全部不可用，只剩纯本地的文档检索、错误码查询、代码生成、沙盒 mock、签名演示。secrets/ 已在 .gitignore 中排除。
账号安全：SESSDATA 等同于账号登录凭证，泄露即交出账号；勿在日志、截图、Issue、对话中暴露。
使用者责任：遵守用户协议、社区公约、开放平台开发者协议与当地法律；本项目不做自动限速，节流责任在调用方，滥用会导致你自己的账号被限流或封停。
无担保：按「现状」提供，官方接口随时可能变更，不承担因使用本项目造成的任何损失。
数据为快照：data/ 是某一时点抓取的结构化快照，一切以官方文档与实际返回为准；生成的代码是骨架，边界条件与错误处理需自行补齐测试。
隐私：本地服务，无遥测、无上报、不向未指定的第三方发送数据；但通过 AI 客户端使用时，你发送的内容与工具返回值会经过该客户端与模型提供方。
不构成法律/合规建议；第三方依赖（@modelcontextprotocol/sdk、zod）自行评估。
下架通道：权利人如认为本仓库内容侵犯权益，开 Issue 或联系仓库所有者，会尽快处理。

_{操作手册：USAGE.md · AI 契约：AGENTS.md · 免责：DISCLAIMER.md}

bili-open-mcp — 哔哩哔哩 / B站 MCP Server#

快速开始#

工具一览（19 个）#

开放平台（签名 / OAuth2）#

主站 Web（浏览器 Cookie）#

wbi 签名#

隐藏能力（开放平台文档里没有的那些）#

举报#

两套凭据，别混#

补上开放平台凭据#

资源与提示#

凭据#

数据从哪来#

统计#

注意#

免责声明（摘要）#