使用方法（详细版）#

bili_oauth  { "action": "status" }
bili_cookie { "action": "status" }

# 开放平台凭据状态
- ❌ clientId       未配置
- ❌ appSecret      未配置
- ❌ accessToken    未配置
- ❌ refreshToken   未配置
凭据文件: C:\path\to\bili-open-mcp\secrets\open-platform.json（不存在）
→ 先去 https://open.bilibili.com 控制台创建应用，拿到 Client ID 与 Secret（或 npm run login 按提示填）

# Cookie 罐  C:\path\to\bili-open-mcp\secrets\cookies.json（文件不存在，jar 为空）

- ❌ SESSDATA           缺失    登录凭证（必需）
- ❌ bili_jct           缺失    CSRF token，POST 必带
- ❌ DedeUserID         缺失    登录用户 uid
- ❌ DedeUserID__ckMd5  缺失    uid 校验
- ❌ buvid3             缺失    设备指纹（风控）
- ❌ buvid4             缺失    设备指纹（风控）
- ❌ b_nut              缺失    设备指纹时间戳
- ❌ sid                缺失    会话 id
- ❌ bili_ticket        缺失    风控票据（部分接口）

共 0 个 cookie，其中 0 个与登录无关（播放器偏好、埋点等）：

下一步:
- 验证登录态: bili_cookie {action:"whoami"}
- 导入: bili_cookie {action:"import", jar:[{name:"SESSDATA", value:"…"}, …]}
- 调用主站接口: bili_web_call {path:"x/web-interface/nav"}

git clone https://github.com/3810220770/bili-open-mcp-bilibili-mcp-server.git
cd bili-open-mcp-bilibili-mcp-server
npm ci

npm run selftest      # 起服务 → 逐个调 19 个工具 / 资源 / 提示 → 生成代码还要过编译
npm run audit         # 11 类数据一致性检查（文档 ↔ 结构化数据是否对得上）
npm run check-config  # 用一份真实的 opencode 项目配置拉起服务，验证客户端侧能连上
npm run build         # 从 Markdown 重新生成 data/*.json 与 llms.txt

tools(19):
  bili_quickstart
  …
===== resources OK: bili://catalog | templates: bili://doc/{ref} | prompts: integrate-bili-api =====
===== catalog / doc 资源 + prompt OK =====
ALL SELFTEST PASSED

node <仓库路径>/src/server.mjs

{
  "mcpServers": {
    "bili-open": {
      "command": "node",
      "args": ["C:/path/to/bili-open-mcp/src/server.mjs"],
      "env": {
        "BILI_CLIENT_ID": "your_client_id",
        "BILI_APP_SECRET": "your_app_secret",
        "BILI_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

# 无凭据（只用文档类工具）
claude mcp add bili-open -- node "C:/path/to/bili-open-mcp/src/server.mjs"

# 带凭据
claude mcp add bili-open \
  -e BILI_CLIENT_ID=xxx -e BILI_APP_SECRET=yyy -e BILI_ACCESS_TOKEN=zzz \
  -- node "C:/path/to/bili-open-mcp/src/server.mjs"

claude mcp list

{
  "mcpServers": {
    "bili-open": {
      "command": "node",
      "args": ["C:/path/to/bili-open-mcp/src/server.mjs"],
      "env": { "BILI_CLIENT_ID": "", "BILI_APP_SECRET": "", "BILI_ACCESS_TOKEN": "" }
    }
  }
}

[mcp_servers.bili-open]
command = "node"
args = ["C:/path/to/bili-open-mcp/src/server.mjs"]
env = { BILI_CLIENT_ID = "your_client_id", BILI_APP_SECRET = "your_app_secret", BILI_ACCESS_TOKEN = "your_access_token" }

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bili-open": {
      "type": "local",
      "command": ["node", "C:/path/to/bili-open-mcp/src/server.mjs"],
      "enabled": true,
      "timeout": 60000,
      "environment": {
        "BILI_CLIENT_ID": "",
        "BILI_APP_SECRET": "",
        "BILI_ACCESS_TOKEN": ""
      }
    }
  }
}

bili_quickstart {}
bili_docs_search { "query": "投稿" }

命中 16 条，显示 3:

#16 [api] 唤起粉端投稿接口说明  (title)
    POST /arcopen/fn/resource/add_share  ·  开放能力 / 视频稿件管理 / 用户端唤起粉端投稿

#168 [event] 投稿失败消息  (title)
    开放能力 / 消息推送 / 推送事件列表 / 视频稿件

#167 [event] 投稿开发浏览消息  (title)
    开放能力 / 消息推送 / 推送事件列表 / 视频稿件

用 bili_api_spec {ref:"#num"} 看参数。

npm run login -- --client-id <ClientID> --secret <Secret>

bili_oauth { "action": "authorize-url", "gourl": "http://127.0.0.1:8848/callback" }

bili_oauth { "action": "exchange", "code": "<code>" }

bili_oauth { "action": "refresh" }

// EditThisCookie 数组
bili_cookie { "action": "import", "jar": [{ "name": "SESSDATA", "value": "…" }, { "name": "bili_jct", "value": "…" }] }

// {name: value} 对象
bili_cookie { "action": "import", "jar": { "SESSDATA": "…", "bili_jct": "…" } }

// "k=v; k=v" 字符串
bili_cookie { "action": "import", "jar": "SESSDATA=…; bili_jct=…" }

bili_cookie { "action": "whoami" }

BILI_COOKIE="SESSDATA=…; bili_jct=…"

# 想放别处，就给绝对路径
BILI_CRED_FILE=C:/my-creds/open-platform.json
BILI_COOKIE_FILE=C:/my-creds/cookies.json

bili_docs_list { "folder": "视频稿件" }
bili_docs_list { "type": "event", "limit": 100 }

bili_docs_search { "query": "upload_token" }
bili_docs_search { "query": "refresh_token", "limit": 5 }

bili_docs_get { "ref": "#12" }
bili_docs_get { "ref": "视频稿件提交", "maxChars": 8000 }

doc: #12  id: f7fc57dd-55a1-5cb1-cba4-61fb2994bf0f  type: api  folder: 开放能力 / 视频稿件管理 / 服务端视频稿件投递  bytes: 3506
(截断到 500/2736 字符，需要更多请提高 maxChars)

---

# 视频稿件提交

Scope: `ARC_BASE`   <font color="green">需要申请权限</font>   <font color="red">需要用户授权</font>
...

bili_endpoints { "scope": "ARC_BASE", "method": "POST" }

命中 9 条，显示前 3

#8 POST /arcopen/fn/archive/video/init ⟨member.bilibili.com⟩  [ARC_BASE]  文件上传预处理
#9 POST /video/v2/part/upload ⟨openupos.bilivideo.com⟩  [ARC_BASE]  文件分片上传
#10 POST /arcopen/fn/archive/video/complete ⟨member.bilibili.com⟩  [ARC_BASE]  文件分片合片

bili_api_spec { "ref": "#12" }
bili_api_spec { "url": "https://member.bilibili.com/arcopen/fn/archive/add-by-utoken" }

# 视频稿件提交  [api]
doc: #12  id: f7fc57dd-55a1-5cb1-cba4-61fb2994bf0f  file: 012_视频稿件提交.md
folder: 开放能力 / 视频稿件管理 / 服务端视频稿件投递
scope: ARC_BASE
POST https://member.bilibili.com/arcopen/fn/archive/add-by-utoken

## url 参数
- upload_token (string, 必填): 通过文件上传预处理(upload_token)授权获取

## body 参数
- title (string, 必填): 稿件标题，长度小于80，短时间内标题不能相同
- cover (string, 可选): 封面地址，必须由上传封面接口得到
- tid (int, 必填): 分区id，由获取分区信息接口得到
- no_reprint (int, 可选): 是否允许转载 0-允许，1-不允许。默认0
- desc (string, 可选): 视频描述，长度小于250
- tag (string, 必填): 视频标签，多个标签用英文逗号分隔，总长度小于200
- copyright (int, 必填): 1-原创，2-转载(转载时source必填)
- source (string, 可选): 如果copyright为转载，则此字段表示转载来源
...

bili_api_prepare { "ref": "#12", "body": { "title": "x" } }

# 视频稿件提交  (#12)
POST https://member.bilibili.com/arcopen/fn/archive/add-by-utoken
## query 缺必填
- upload_token (string) 通过文件上传预处理(upload_token)授权获取
## body 缺必填
- tid (int) 分区id，由获取分区信息接口得到
- tag (string) 视频标签，多个标签用英文逗号分隔，总长度小于200
- copyright (int) 1-原创，2-转载(转载时source必填)
## 最终 query
```json
{}
```
## 最终 body
```json
{"title":"x"}
```
## 下一步
- 真调: bili_api_call { "ref": "12", "query": ..., "body": ... }
- 看签名: bili_api_sign { "url": "https://member.bilibili.com/arcopen/fn/archive/add-by-utoken", "body": ... }

bili_scopes { }                              // 20 个 scope 全览
bili_scopes { "scope": "SHOP_ORDER_INFO" }   // 该 scope 下的端点
bili_scopes { "ref": "#12" }                 // 该接口要什么 scope

共 20 个 scope，94 个端点带标注:

- ATC_BASE: 14 个端点  (例: #21 文章提交)
- ARC_BASE: 12 个端点  (例: #8 文件上传预处理)
- SHOP_COMMODITY_INFO: 10 个端点  (例: #68 商品发布)
- SHOP_LOGISTICS_INFO: 10 个端点  (例: #86 发货回调)
...
- UPOWER_ORDER_DATA: 1 个端点  (例: #110 查询充电记录)

bili_error_lookup { "code": "4002" }

4002: 签名异常

bili_error_lookup { "code": "1230", "fuzzy": true }

bili_codegen { "ref": "#12", "lang": "python" }

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
接口: 视频稿件提交  (doc #12)
POST https://member.bilibili.com/arcopen/fn/archive/add-by-utoken
scope: ARC_BASE
由 bili-open-mcp 生成；TODO 处需填真实值，未执行的步骤请自行补齐
"""
import hashlib, hmac, json, os, time, urllib.parse, urllib.request, uuid

CLIENT_ID = os.environ.get("BILI_CLIENT_ID", "YOUR_CLIENT_ID")
...

bili_api_sign { "url": "https://member.bilibili.com/arcopen/fn/archive/video/param", "query": { "a": 1 } }

## 待签名串
x-bili-accesskeyid:YOUR_CLIENT_ID
x-bili-content-md5:d41d8cd98f00b204e9800998ecf8427e
x-bili-signature-method:HMAC-SHA256
x-bili-signature-nonce:b8cdd7f4-cd3d-4f08-ac68-856bd82b7f05
x-bili-signature-version:2.0
x-bili-timestamp:1793433370
## 请求头
Accept: application/json
Content-Type: application/json
Authorization: 762e736a5a8970abbc7d63b7329ebd7d975c5007c275a0be6adff0884f6139af
X-Bili-Accesskeyid: YOUR_CLIENT_ID
X-Bili-Content-Md5: d41d8cd98f00b204e9800998ecf8427e
...
## curl
curl --location --request GET 'https://member.bilibili.com/arcopen/fn/archive/video/param?a=1' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
...

bili_api_call { "ref": "#12", "query": { "upload_token": "…" }, "body": { … } }
bili_api_call { "ref": "#12", "dryRun": true }        // 只看将要发的请求
bili_api_call { "url": "https://member.bilibili.com/arcopen/fn/archive/video/param", "method": "GET" }

## dryRun — 未发送
```
curl --location --request POST 'https://member.bilibili.com/arcopen/fn/archive/add-by-utoken' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: c0fdbe2094f5b288432f2d02374126735f4d19e266f26fb4ac70d663a5dff271' \
--header 'X-Bili-Accesskeyid: YOUR_CLIENT_ID' \
--header 'X-Bili-Content-Md5: d41d8cd98f00b204e9800998ecf8427e' \
--header 'X-Bili-Signature-Method: HMAC-SHA256' \
--header 'X-Bili-Signature-Nonce: 8bb260eb-b578-4f3d-8aac-35b63c811bf4' \
--header 'X-Bili-Signature-Version: 2.0' \
--header 'X-Bili-Timestamp: 1793433370' \
--header 'Access-Token: YOUR_ACCESS_TOKEN'
```

bili_upload_plan { "fileSizeMB": 250 }
bili_upload_plan { "fileSizeBytes": 314572800, "chunkMB": 10, "filename": "video.mp4" }

# 投稿上传计划
文件: video.mp4  250.0 MB
模式: 分片（10MB/片，utype=0）
分片数: 25，请求数: 28

## 调用顺序
1. POST /arcopen/fn/archive/video/init          body {"name":"video.mp4","utype":"0"}  → upload_token
2. POST https://openupos.bilivideo.com/video/v2/part/upload?upload_token=<token>&part_number=N   body=裸分片字节  ×25
3. POST /arcopen/fn/archive/video/complete        url upload_token=<token>
4. POST /arcopen/fn/archive/add-by-utoken   url upload_token=<token>   body 见 #12

## 分片表
| part_number | 起始 offset | 结束 offset | 字节数 |
| --- | --- | --- | --- |
| 1 | 0 | 10485759 | 10485760 |
| 2 | 10485760 | 20971519 | 10485760 |
...

bili_mock { "action": "list" }                       // 43 个 mock 接口
bili_mock { "action": "map", "ref": "12" }           // 正式接口 → mock 地址
bili_mock { "action": "call", "mockUrl": "https://member.bilibili.com/mock/arcopen/fn/archive/add" }

bili_webhook { "action": "detail", "ref": "164" }
bili_webhook { "action": "verify-code", "lang": "node" }

1. 取收到的原始 body 字节，拼 app_secret + body 做 SHA1
2. 与请求头 x-bilibili-signature 比对
⚠ 必须用原始字节，不要重新序列化 —— 重排 key 会验签失败

{ "event": "verify_webhooks", "content": { "data": 1371848576 }, "timestamp": "2021-01-01 12:01:01" }

bili_ws_protocol { }
bili_ws_protocol { "code": "python" }   // 额外生成内联 Python 客户端

# 直播间长连协议（文档 #43 / #44 / #45 / #46）

## 建立流程
1. POST /arcopen/fn/live/room/ws-start  (scope LIVE_ROOM_DATA)
   → data.conn_id, data.websocket_info.wss_link[], data.websocket_info.auth_body
2. 连 wss_link[0]，第一个包必须是 OP_AUTH(7)，body = auth_body（JSON 字符串，UTF-8）
3. 每 30s 发 OP_HEARTBEAT(2)，body 为空
4. 服务端推 OP_SEND_SMS_REPLY(5) 即消息；OP_HEARTBEAT_REPLY(3) 是心跳回执

## 包头（16 字节，全大端）
  Packet Length uint32   # 含 header 的总长
  Header Length uint16   # 固定 16
  Version       uint16   # 0=body 为明文, 2=body 为 zlib 压缩
  Operation     uint32   # 见下表
  Sequence ID   uint32   # 保留字段，可忽略
  Body          bytes

bili_web_call { "path": "x/web-interface/nav" }
bili_web_call { "path": "x/relation/modify", "method": "POST", "form": { "fid": 123, "act": 5, "re_src": 11 } }
bili_web_call { "url": "https://api.bilibili.com/x/web-interface/view?bvid=BV1xx411c7mD" }

## dryRun — 未发送
```
GET https://www.bilibili.com/x/web-interface/nav

请求头:
  User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36
  Referer: https://www.bilibili.com/
  Accept: application/json, text/plain, */*
```

jar: C:\path\to\bili-open-mcp\secrets\cookies.json（0 个 cookie）

你   ：我想用开放平台投稿视频，帮我理一遍。
AI   ：bili_docs_search { "query": "投稿" }
       → bili_api_spec { "ref": "#12" }
       → bili_scopes { "ref": "#12" }          // 需要申请 ARC_BASE
       → bili_upload_plan { "fileSizeMB": 250 } // 分片计划
       → bili_codegen { "ref": "#12", "lang": "python" }

bili_oauth  { "action": "status" }                          // 先确认凭据在
bili_api_prepare { "ref": "#4" }                            // 查必填
bili_api_call { "ref": "#4", "dryRun": true }               // 看请求
bili_api_call { "ref": "#4" }                               // 真发
bili_error_lookup { "code": "<返回的 code>" }                // 非 0 就查

1. bili_upload_plan { "fileSizeMB": 250 }                    // 拿调用顺序与分片表
2. POST /arcopen/fn/archive/video/init          → upload_token
3. POST openupos.bilivideo.com/video/v2/part/upload?upload_token=…&part_number=N   ×25   （裸二进制）
4. POST /arcopen/fn/archive/video/complete
5. POST /arcopen/fn/archive/add-by-utoken       （body 见 #12）
6. 收 Webhook「投稿成功 / 投稿失败」事件（bili_webhook {action:"detail", ref:"…"}）

bili_cookie { "action": "import", "jar": "SESSDATA=…; bili_jct=…" }
bili_cookie { "action": "whoami" }
bili_web_call { "path": "x/web-interface/nav" }
bili_web_call { "path": "x/space/wbi/acc/info", "query": { "mid": 2 } }   // 自动 wbi 签名

bili_ws_protocol { }                       // 先读协议
bili_api_call { "url": "https://member.bilibili.com/arcopen/fn/live/room/ws-start", "method": "POST" }
→ python examples/live_ws.py --conn-id <id> --auth-body '<auth_body>' --wss 'wss://…'

bili_webhook { "action": "list" }                       // 选事件
bili_webhook { "action": "detail", "ref": "164" }       // 看字段
bili_webhook { "action": "verify-code", "lang": "python" }   // 拿验签代码

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

npm run build     # 重新解析
npm run audit     # 校验一致性