Bilibili Server Unofficial(Video Subtitles And Comments)

npm version License: GPL v3 npm downloads

Bilibili MCP server — 让 Claude、Cursor、Codex 等 AI 客户端直接读取 Bilibili 视频字幕、转录、元数据和热门评论的 MCP server。

🌐 English Documentation · 📜 更新日志 · 📦 npm · 🚀 Release v1.4.0

[!TIP] ⚠️ 你可以把下方“用 agent 工具帮你安装”的提示词复制给 Codex、Claude Code、Cursor 等 agent，让它帮你完成 MCP 客户端接入和 Cookie 配置引导。为了稳定获取字幕、转录和评论，安装后仍需配置 B 站 Cookie(agent会引导你)；不要把 Cookie 写进 MCP 客户端配置。Metadata 可能无需 Cookie。详见 凭证配置。

---

⚡ 快速开始

选择你正在使用的 AI 客户端，点击后可直接跳转到详细配置方法：

用 agent 工具帮你安装

如果你正在使用 Codex、Claude Code、Cursor、Qoder、Kimi Code、Antigravity、Windsurf、Cline 等带 agent 的工具，可以把下面这段话复制给你的 agent，让它先在本 README 中找到对应客户端的安装方式，再帮你写入 MCP 配置：

请帮我安装 Bilibili MCP server：@xzxzzx/bilibili-mcp。

请先到 https://github.com/365903728-oss/bilibili-mcp 阅读项目 README 的“快速开始”和“客户端接入方式”章节，找到我当前使用的 agent/客户端对应的 MCP 配置方式，然后按该客户端的官方配置位置添加这个 server。

MCP server 配置要求：
- server 名称：bilibili-mcp
- command：npx
- args：["-y", "@xzxzzx/bilibili-mcp"]

不要把真实 Bilibili Cookie 写入 MCP 客户端配置文件、客户端配置里的 env 字段、args 或聊天消息中。
添加 MCP server 后，请继续引导我单独运行下面的命令，把 Cookie 保存到本机凭证配置；MCP server 启动后会自动读取这些凭证：

npx -y @xzxzzx/bilibili-mcp config
npx -y @xzxzzx/bilibili-mcp check

连接 MCP server 后，如可用，请调用 get_credential_setup_instructions 或 check_bilibili_credentials，确认我完成 Cookie 配置。

• Codex app / Codex CLI
• Claude Code
• Claude Desktop
• OpenCode
• OpenClaw
• Hermes
• WorkBuddy
• CodeBuddy
• Trae CN
• Trae International
• Trae SOLO CN
• Trae SOLO International
• Qoder IDE / Qoder CLI / QoderWork
• Kimi Code / Kimi Code CLI
• Antigravity / Antigravity CLI
• Pi
• Oh My Pi
• Crush
• DeepSeek-TUI
• Deep Code
• Reasonix
• GitHub Copilot CLI
• Cursor
• Cline
• Kilo Code
• VS Code
• GitHub Copilot (VS Code)
• Windsurf
• Zed
• Cherry Studio
• LobeHub / LobeChat
• AstrBot
• nanobot

---

📑 目录

• ⚡ 快速开始
• 🌟 功能特性
  • 1. 视频总结 (get_video_info)
  • 2. 评论总结 (get_video_comments)
  • 3. 视频转录 (get_video_transcript)
  • 4. 视频元数据 (get_video_metadata)
  • 5. 凭证助手工具
  • 6. 行为说明与错误处理
• 📋 环境要求
• 🚀 客户端接入方式
• ⚙️ 凭证配置
• 🧭 该用哪个工具
• 💡 工具调用示例
• 🛡️ API 限流机制
• 🛠️ 开发指南
• ⚖️ 安全性与免责声明
• 💬 反馈与建议

---

🌟 功能特性

1. 视频总结 (get_video_info)

• 优先获取视频的 CC 或 AI 字幕
• 无字幕时自动降级为视频标题、简介和标签
• 支持多语言字幕选择（默认优先简体中文）
• 可手动指定偏好字幕语言（如 en, zh-Hant 等）

2. 评论总结 (get_video_comments)

• 获取视频热门评论，辅助判断视频真实口碑
• 自动过滤表情占位符（如 [doge]）以保持文本整洁
• 优先保留包含时间戳的评论（如 05:20），方便定位高能片段
• 支持两种详细程度：
  • brief: 10 条热门评论速览
  • detailed: 20 条热门评论 + 高赞连带回复
• 可选参数：
  • limit: 显式评论数量 1-50，覆盖 detail_level 的默认数量
  • sort: 排序方式 "hot"（按热度，默认）或 "time"（按时间）
  • include_replies: 是否包含高赞回复（默认 true）

3. 视频转录 (get_video_transcript)

• 返回纯字幕文本，按行合并
• 支持指定偏好语言（默认按 zh-Hans > ai-zh > zh-CN > zh-Hant > en 优先级选择）
• 可选参数：
  • preferred_lang: 偏好字幕语言代码
  • fallback_to_description: 字幕不可用时是否降级为视频描述（默认 false）
• 默认不降级：无字幕时返回 SUBTITLE_UNAVAILABLE 错误
• Cookie 失效时始终返回 COOKIE_EXPIRED，不静默降级

4. 视频元数据 (get_video_metadata)

• 返回视频标题、作者、时长、发布时间、描述、标签、播放/点赞/投币等统计信息
• 不获取字幕或评论
• 仅需 bvid_or_url 参数

5. 凭证助手工具

• get_credential_setup_instructions: 返回安全的 Bilibili Cookie 配置命令和说明。AI agent 安装此 MCP 后可调用此工具引导用户完成配置。
• check_bilibili_credentials: 检查凭证是否已配置并处于登录状态，不返回任何 Cookie 值。配置缺失或失效时返回下一步操作指引。

6. 行为说明与错误处理

• Cookie 过期智能检测：当字幕获取为空时自动验证登录状态，区分“无字幕视频”与“凭证失效”，并抛出明确的 COOKIE_EXPIRED 错误，避免静默降级。

无 Cookie 行为

• 部分公开视频元数据（get_video_metadata）可能在未登录状态下工作。
• 字幕（get_video_info、get_video_transcript）在未登录时可能无法获取、不完整或返回空结果。
• 评论（get_video_comments）在未登录时可能不完整、被限流或返回空列表。
• 不建议依赖无 Cookie 模式获取字幕或评论。

Cookie 凭据来源

• Cookie 凭据应通过 .env 文件、环境变量或凭据管理工具提供。
• 支持的环境变量：BILIBILI_SESSDATA、BILIBILI_BILI_JCT、BILIBILI_DEDEUSERID。
• 切勿在源码、脚本、文档、测试、日志或示例中硬编码 Cookie 值。
• 如果 Cookie 值曾出现在仓库历史中，应尽快到 Bilibili 账号设置中轮换/失效旧 Cookie。

预期错误码

错误码	含义	调用方建议
VALIDATION_ERROR	输入参数不合法	检查并修正 bvid_or_url 或其他参数
COOKIE_EXPIRED	Cookie 已失效或未登录	用户应更新/轮换 Bilibili 凭据
SUBTITLE_UNAVAILABLE	视频无可用的字幕	对 get_video_transcript 可重试并设置 fallback_to_description: true

📋 环境要求

• Node.js: v18.0.0 或更高版本
• Bilibili 账号凭证 (Cookie)

---

🚀 客户端接入方式

[!NOTE] 不要在 MCP 客户端配置文件中写入真实 Cookie。建议先用 bilibili-mcp config 保存到本机凭证配置，或在运行环境中提供环境变量；MCP server 启动后会自动读取这些凭证。详见 ⚙️ 凭证配置。

[!IMPORTANT] 如果你是正在帮用户安装本 MCP 的 AI agent：不要只写入 MCP 配置就结束。添加 bilibili-mcp server 后，必须继续提醒并引导用户完成 Bilibili Cookie 配置。连接 MCP server 后，agent 也可调用 get_credential_setup_instructions 或 check_bilibili_credentials 工具来引导用户。

推荐引导用户运行：

npx -y @xzxzzx/bilibili-mcp config
npx -y @xzxzzx/bilibili-mcp check

如果用户已经全局安装，也可以使用：

bilibili-mcp config
bilibili-mcp check

config 用于输入 SESSDATA、bili_jct、DedeUserID；check 用于确认凭证已加载。不要要求用户把 Cookie 粘贴进 Claude、Cursor、Codex、Qoder、Kimi 或其他 MCP 客户端配置文件。

Codex app / Codex CLI

Codex app、Codex CLI 和 Codex IDE extension 共用 MCP 配置。优先使用下面任一方式添加：

Codex app

打开 Settings → Integrations & MCP，添加自定义 MCP server：

• Command: npx
• Arguments: ["-y", "@xzxzzx/bilibili-mcp"]

Codex CLI

codex mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp

配置后，在 Codex CLI TUI 中运行 /mcp 查看 server 状态。

手动配置

也可以直接编辑 Codex 配置文件：

• 用户级：~/.codex/config.toml
• 项目级：.codex/config.toml（仅在 Codex 信任该项目时加载）

[mcp_servers.bilibili-mcp]
command = "npx"
args = ["-y", "@xzxzzx/bilibili-mcp"]

Claude Code

claude mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp

默认会作为当前项目的本地 MCP server 保存。配置后可在 Claude Code 中运行 /mcp，或在终端运行 claude mcp list 检查连接状态。

如果希望所有项目都可用，可使用用户级 scope：

claude mcp add --scope user bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp

也可以手动编辑 ~/.claude.json，在对应项目或用户配置下添加与 Claude Desktop 相同的 JSON。

Claude Desktop

打开 Claude Desktop 的 Settings → Developer → Edit Config，或直接编辑：

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

保存后重启 Claude Desktop。该配置适合本地 stdio MCP server；不要在 env、args 或配置文件里写真实 Cookie。

OpenCode

编辑 OpenCode 配置文件 ~/.config/opencode/opencode.json，在 mcp 下添加本地 MCP server：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bilibili-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@xzxzzx/bilibili-mcp"],
      "enabled": true
    }
  }
}

OpenCode 会把 MCP tools 加入可用工具上下文。使用时可在提示词中明确要求使用 bilibili-mcp。

OpenClaw

使用 OpenClaw 的 MCP registry 注册本服务：

openclaw mcp set bilibili-mcp '{"command":"npx","args":["-y","@xzxzzx/bilibili-mcp"]}'

检查配置：

openclaw mcp list
openclaw mcp show bilibili-mcp

也可以在 OpenClaw 配置中加入同等结构：

{
  "mcp": {
    "servers": {
      "bilibili-mcp": {
        "command": "npx",
        "args": ["-y", "@xzxzzx/bilibili-mcp"]
      }
    }
  }
}

openclaw mcp set 只写入 OpenClaw 的 MCP server 定义；具体运行时是否启用，取决于你的 OpenClaw agent/runtime 配置。

Hermes

编辑 ~/.hermes/config.yaml，在 mcp_servers 下添加：

mcp_servers:
  bilibili-mcp:
    command: "npx"
    args: ["-y", "@xzxzzx/bilibili-mcp"]

如果你已经在运行 Hermes 会话，使用 /reload-mcp 重新加载 MCP 配置；也可以开启一个新的 Hermes 会话。

Cursor

Cursor 编辑器和 Cursor CLI (cursor-agent) 共用同一套 mcp.json 配置。CLI 会自动读取编辑器已配置的 MCP server。

方式一：Cursor 编辑器

在 Cursor 设置中打开 MCP / MCP Servers，添加自定义 stdio server；也可以直接编辑配置文件。

项目级配置：

.cursor/mcp.json

全局配置：

~/.cursor/mcp.json

配置内容：

{
  "mcpServers": {
    "bilibili-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

方式二：Cursor CLI

Cursor CLI 使用同一份 mcp.json，无需单独再写一份配置。可用下面命令检查：

cursor-agent mcp list
cursor-agent mcp list-tools bilibili-mcp

如果 MCP server 需要认证，Cursor CLI 使用：

cursor-agent mcp login bilibili-mcp

Cline

Cline 支持本地 STDIO 和远程 MCP。编辑 Cline MCP 配置文件，加入：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cline CLI 用户可用 JSON 方式查看或管理 MCP 设置：

cline config mcp --json

配置后在 Cline 的 MCP 面板确认 server 已启用。不要把真实 Cookie 写进 Cline 配置。

Kilo Code

Kilo Code 的 MCP server 写在主配置文件的 mcp 对象下。

配置位置：

• 全局：~/.config/kilo/kilo.jsonc
• 项目级：kilo.jsonc
• 项目级：.kilo/kilo.jsonc

添加：

{
  "mcp": {
    "bilibili-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@xzxzzx/bilibili-mcp"],
      "enabled": true,
      "timeout": 10000
    }
  }
}

也可以在 Kilo Code 设置 UI 中打开 Agent Behaviour → MCP Servers 添加。项目级配置优先于全局配置。

VS Code

VS Code 原生支持 MCP 配置。工作区配置可通过命令面板打开：

MCP: Open Workspace Folder MCP Configuration

这会创建或打开：

.vscode/mcp.json

添加：

{
  "servers": {
    "bilibili-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

用户级配置可用命令面板打开：

MCP: Open User Configuration

VS Code MCP 还支持 HTTP、SSE、Windows named pipe 和 Unix socket。配置后可在 VS Code 的 MCP server 列表中启动、停止或查看 server 状态。使用本项目时不要把真实 Cookie 写进 .vscode/mcp.json。

GitHub Copilot (VS Code)

GitHub Copilot Chat 在 VS Code 中读取 VS Code MCP 配置。工作区配置可写入：

.vscode/mcp.json

添加：

{
  "servers": {
    "bilibili-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

也可以用命令面板打开 MCP: Open User Configuration 配置全局 MCP。配置后在 Copilot Chat Agent Mode 中使用该 server 的工具。

WorkBuddy

WorkBuddy 官方文档推荐通过界面配置 MCP。进入侧边栏 插件 → MCP 服务器 → 配置 MCP，然后添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

也可以按作用域编辑配置文件：

• 用户级：~/.workbuddy/mcp.json
• 项目级：<项目目录>/.workbuddy/mcp.json

CodeBuddy

方式一：CodeBuddy CLI

CodeBuddy CLI 可以直接添加 stdio MCP server：

codebuddy mcp add --scope user bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp

检查配置：

codebuddy mcp list
codebuddy mcp get bilibili-mcp

方式二：CodeBuddy IDE

在 CodeBuddy IDE 侧栏对话面板右上角打开 CodeBuddy Settings → MCP → Add MCP，填入：

{
  "mcpServers": {
    "bilibili-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"],
      "description": "Bilibili MCP server"
    }
  }
}

如果使用项目级 .mcp.json，请确认 CodeBuddy settings 允许启用该项目 MCP server。

Trae CN

在 Trae CN 中打开 AI 对话窗口右上角设置入口，进入 MCP 配置；也可以直接编辑 MCP 配置文件。

常见配置路径：

• Windows: %APPDATA%\Trae\User\settings\mcp.json
• macOS: ~/Library/Application Support/Trae/User/settings/mcp.json
• 项目级：.trae/mcp.json

添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

如果你使用项目级 .trae/mcp.json，请在 Trae 的 MCP 管理面板中确认项目配置导入已启用。

Trae International

在 Trae 国际版中打开 AI 对话窗口右上角 Settings → MCP，选择 Add 或手动配置 MCP server。

如果需要直接编辑项目级配置，可创建 .trae/mcp.json：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

Trae 支持 stdio MCP server；本项目使用 npx 启动 stdio server。

Trae SOLO CN

Trae SOLO CN 是 Trae 中国版的 SOLO 工作方式。官方公开文档没有给出独立于 Trae MCP 的专属配置文件；当前可按 Trae 项目级 MCP 配置接入，然后在 SOLO Coder 中使用。

在项目根目录创建 .trae/mcp.json：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

然后在 Trae 的 MCP 管理面板中确认项目配置导入已启用，并在 SOLO Coder 中使用该 MCP server。

Trae SOLO International

Trae SOLO International 已存在，官方 FAQ 说明国际版 SOLO 面向 Pro 用户。没有找到单独的 SOLO 专属 MCP JSON 格式；可使用 Trae International 的 MCP 配置方式，然后在 SOLO Coder / Builder with MCP 中调用。

项目级配置同样使用 .trae/mcp.json：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

如果使用 Trae International 的 UI，打开 AI 对话窗口右上角 Settings → MCP，手动添加同等 mcpServers 配置。

Qoder IDE / Qoder CLI / QoderWork

Qoder 有多种形态，MCP 入口略有不同：Qoder IDE 在设置页配置，Qoder CLI 用 qodercli mcp 命令，QoderWork 桌面端在 MCP Servers 页面添加。

Qoder IDE

打开右上角用户图标 → Qoder Settings → MCP，在 My Servers 中点击 + Add，然后添加本地 STDIO server：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

Qoder 文档说明 Streamable HTTP 可按 SSE endpoint 方式配置并自动检测；本项目是本地 stdio server，因此使用上面的 command / args 配置。

Qoder CLI

Qoder CLI 可直接添加 stdio MCP server：

qodercli mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp

常用检查命令：

qodercli mcp list

如果 Qoder CLI 已经在运行，添加或修改 MCP server 后在会话中执行 /mcp reload 重新发现工具。默认 scope 是当前项目本地配置；也可以用 -s user 保存到用户级配置，或用 -s project 写入项目级 .mcp.json。

常见配置文件位置：

• 用户级：~/.qoder/settings.json
• 当前项目本地：.qoder/settings.local.json
• 项目级共享：.mcp.json

QoderWork

打开 QoderWork desktop app → Settings → MCP Servers，点击右上角 + Add。

最快方式是选择 Paste JSON Config，并粘贴：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

也可以选择 Fill in Config Manually，Server Type 选择 STDIO：

• Server Name: bilibili-mcp
• Command: npx -y @xzxzzx/bilibili-mcp

添加后在 Custom Servers 中确认 server 已启用，并展开查看可用 tools。不要在 Qoder / QoderWork 的 MCP 配置中写真实 Cookie；凭证请使用 bilibili-mcp config 或环境变量配置。

Kimi Code / Kimi Code CLI

Kimi Code CLI 可作为 MCP client 连接本地 stdio server。当前 Kimi Code 文档推荐把 MCP server 写入 mcp.json：

• 用户级：~/.kimi-code/mcp.json
• 项目级：.kimi-code/mcp.json

添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

项目级 .kimi-code/mcp.json 只对当前仓库生效，并会覆盖同名用户级配置。进入 Kimi Code CLI 后，可以用：

/mcp
/mcp-config

/mcp 查看连接状态和工具列表，/mcp-config 交互式添加、编辑或删除 MCP server。

旧版 Kimi CLI 文档也提供过 kimi mcp add 命令；如果你使用的安装版本仍支持该命令，可用：

kimi mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp
kimi mcp list
kimi mcp test bilibili-mcp

不要在 Kimi Code 的 mcp.json、env 或命令参数中写真实 Cookie；凭证请用 bilibili-mcp config 或环境变量配置。

Antigravity / Antigravity CLI

Gemini CLI 已迁移到 Antigravity CLI。新的 MCP 配置不再写在 ~/.gemini/settings.json，而是使用独立的 mcp_config.json。

Antigravity IDE 可通过 MCP Store → Manage MCP Servers → View raw config 打开配置；Antigravity CLI 可通过 /mcp 管理 MCP servers。

常见配置路径：

• Antigravity IDE：~/.gemini/antigravity/mcp_config.json
• Antigravity CLI 全局：~/.gemini/antigravity-cli/mcp_config.json
• Antigravity CLI 工作区：.agents/mcp_config.json

添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

保存后重启 Antigravity / Antigravity CLI，或在 CLI 中使用 /mcp 检查 server 是否加载。

Pi

Pi 通过 pi-mcp-adapter 使用 MCP。先安装 adapter：

pi install npm:pi-mcp-adapter

重启 Pi 后，优先使用项目级共享配置：

.mcp.json

添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

也可以使用用户级共享配置：

~/.config/mcp/mcp.json

Pi 还支持 Pi 专属覆盖文件：

• 全局：~/.pi/agent/mcp.json
• 项目级：.pi/mcp.json

如果你已经在 Cursor、Claude Code、Codex、Windsurf 等客户端里配置过 MCP，可在 Pi 中运行 /mcp setup 导入或生成配置；终端也可运行：

pi-mcp-adapter init

Pi 默认 lazy 连接 MCP server，只有实际调用工具时才启动。进入 Pi 后使用 /mcp 查看 server 状态和工具列表。不要在 Pi 的 MCP 配置里写真实 Cookie；凭证请用 bilibili-mcp config 或环境变量配置。

Oh My Pi

Oh My Pi (omp) 原生支持 MCP，优先使用 OMP 专属配置文件：

• 项目级：.omp/mcp.json
• 用户级：~/.omp/agent/mcp.json

也可以使用可被其他 MCP client 复用的项目根配置：

• mcp.json
• .mcp.json

添加：

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "bilibili-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

也可以在 OMP 会话中使用引导式配置：

/mcp add

修改配置后使用：

/mcp reload
/mcp list
/mcp test bilibili-mcp

OMP 支持 stdio、http 和 sse MCP。不要在 env、args 或配置文件中写真实 Cookie。

Crush

Crush 支持项目级和用户级 JSON 配置，MCP server 写在 mcp 对象下。

配置优先级：

• 项目级：.crush.json
• 项目级：crush.json
• 用户级：~/.config/crush/crush.json

添加：

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "bilibili-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

Crush 也支持 HTTP 和 SSE MCP。不要在 env 或 args 中写真实 Cookie；凭证请使用本项目的 CLI 向导或环境变量。

DeepSeek-TUI

DeepSeek-TUI 同时是 MCP client 和 MCP server。作为 MCP client 时，可用 deepseek mcp add 添加本项目：

deepseek mcp add bilibili-mcp -- npx -y @xzxzzx/bilibili-mcp

也可以编辑：

~/.deepseek/mcp.json

添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

可用 deepseek mcp list 和 deepseek mcp validate 检查配置。DeepSeek-TUI 暴露的 MCP 工具通常以 mcp_<server>_<tool> 形式出现。

Deep Code

Deep Code 使用 ~/.deepcode/settings.json 配置 MCP server。把 bilibili-mcp 加到 mcpServers：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["@xzxzzx/bilibili-mcp"]
    }
  }
}

Deep Code 文档说明 command 为 npx 时会自动补充 -y。配置后启动 deepcode，输入 /mcp 查看 MCP server 状态和可用工具。

Reasonix

Reasonix 支持原生 MCP。最简单的方式是启动时传入 --mcp：

npx reasonix code --mcp "bilibili=npx -y @xzxzzx/bilibili-mcp"

也可以编辑全局配置：

~/.reasonix/config.json

在 mcp 数组中添加：

{
  "mcp": [
    "bilibili=npx -y @xzxzzx/bilibili-mcp"
  ]
}

Reasonix 的格式是 name=command arg1 arg2。如果需要项目级覆盖，可放在项目的 .reasonix/ 下。

GitHub Copilot CLI

GitHub Copilot CLI 可在交互模式里使用 /mcp add 添加 MCP server。按表单选择 STDIO 或 Local，然后填入：

• Server Name: bilibili-mcp
• Command: npx
• Args: -y @xzxzzx/bilibili-mcp

也可以编辑用户级配置：

~/.copilot/mcp-config.json

添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"],
      "env": {},
      "tools": ["*"]
    }
  }
}

项目级配置可用 .mcp.json 或 .github/mcp.json，并且会优先于用户级同名 server。进入 Copilot CLI 后可用 /mcp show 查看状态。

Windsurf

Windsurf 的 MCP 由 Cascade 使用。官方入口是 Cascade 面板右上角的 MCPs 图标，或 Windsurf Settings → Cascade → MCP Servers。

方式一：Cascade / MCP Servers UI

打开 MCP Marketplace 或 MCP Servers 设置后，添加自定义 stdio MCP server：

• Command: npx
• Arguments: ["-y", "@xzxzzx/bilibili-mcp"]

Windsurf 也支持 MCP deeplink；如果你在文档或网页中提供安装入口，可以使用 windsurf://windsurf-mcp-registry?serverName=<server-name> 打开对应 MCP registry 页面。

方式二：Raw config

直接编辑：

~/.codeium/windsurf/mcp_config.json

添加：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

Windsurf/Cascade 支持 stdio、Streamable HTTP 和 SSE MCP。本项目使用本地 stdio server，因此不要把真实 Bilibili Cookie 写进该配置文件；凭证请用 bilibili-mcp config 或环境变量配置。

Zed

Zed 使用 context_servers 配置 MCP，不使用 mcpServers。可以通过 Agent Panel 的 settings view 添加自定义 server，也可以直接编辑 settings.json。

方式一：Agent Panel UI

打开 Agent Panel 的 Settings view，点击 Add Custom Server，填入本项目的 stdio server 配置。

配置后，在 Agent Panel 的 settings view 中查看 server 名称旁边的状态圆点；绿色表示 server active。

方式二：settings.json

用户级设置可通过 Zed 的 zed: open settings 打开。项目级设置可写入：

.zed/settings.json

添加：

{
  "context_servers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

方式三：Zed extension

Zed 也支持以 extension 的方式安装 MCP server。通用自定义 server 用上面的 context_servers 更直接；如果未来本项目发布 Zed MCP extension，再改用 extension 安装。

Zed 支持 MCP Tools 和 Prompts，也支持远程 MCP；远程 server 使用 url 和可选 headers。本项目是本地 stdio server，不要在 Zed 配置里写真实 Bilibili Cookie。

Cherry Studio

Cherry Studio 在 Settings → MCP Server 中添加 MCP server。添加本项目时选择 STDIO：

• Name: bilibili-mcp
• Type: STDIO
• Command: npx
• Parameters: -y @xzxzzx/bilibili-mcp

保存后，Cherry Studio 会启动该 MCP server；在聊天窗口中启用对应 MCP server 后即可调用工具。

LobeHub / LobeChat

LobeChat Desktop 支持导入 MCP server JSON。打开：

Settings → Default Agent → Plugin Settings → Custom Plugins → Quick JSON Configuration Import

粘贴：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

安装后，在对应 Agent 的插件设置中启用该 MCP server。不要把真实 Cookie 写进 LobeChat 配置；凭证请通过本项目 CLI 或环境变量配置。

AstrBot

AstrBot 通过 WebUI 管理 MCP。先确保 AstrBot 运行环境可使用 npm 和 node，然后在 WebUI 的 MCP 服务器管理入口添加本地 MCP server：

{
  "mcpServers": {
    "bilibili-mcp": {
      "command": "npx",
      "args": ["-y", "@xzxzzx/bilibili-mcp"]
    }
  }
}

如果 AstrBot 运行在 Docker 中，需要确保容器内已安装 Node.js / npm，且容器能访问运行 MCP server 所需的网络。

nanobot

nanobot 的配置文件是：

~/.nanobot/config.json

在 tools.mcpServers 下添加：

{
  "tools": {
    "mcpServers": {
      "bilibili-mcp": {
        "command": "npx",
        "args": ["-y", "@xzxzzx/bilibili-mcp"]
      }
    }
  }
}

nanobot 的 MCP 配置兼容 Claude Desktop / Cursor 风格；也支持远程 MCP 的 url 和 headers。凭证仍应由本项目 CLI 或环境变量管理，不要写入 nanobot 配置。

⚙️ 凭证配置

如果你使用上方“用 agent 工具帮你安装”的提示词，agent 会引导你完成本节步骤；通常不需要手动阅读完整配置。这里用于说明 Cookie 保存位置、安全边界，以及 Docker、本地开发等手动场景。为了稳定获取字幕、转录和评论，建议配置 Bilibili Cookie；公开视频元数据可能无需 Cookie。

推荐方式：让 agent 引导你配置

npx -y @xzxzzx/bilibili-mcp config
npx -y @xzxzzx/bilibili-mcp check

如果你使用上方“用 agent 工具帮你安装”的提示词，agent 会在添加 MCP server 后引导你运行这两个命令。config 输入不会在终端回显，会把 Cookie 保存到本机凭证配置；MCP server 启动后会自动读取，不会写入 MCP 客户端配置或仓库。

如果已经全局安装，也可以运行：

bilibili-mcp config
bilibili-mcp check

环境变量方式

适合 Docker、本地开发或你明确知道当前 MCP server 运行环境的情况。不要把真实 Cookie 写进可共享的 MCP 客户端配置文件。

变量名	说明
BILIBILI_SESSDATA	Bilibili 登录 Cookie 中的 SESSDATA
BILIBILI_BILI_JCT	Bilibili 登录 Cookie 中的 bili_jct
BILIBILI_DEDEUSERID	Bilibili 用户 ID

.env 示例：

BILIBILI_SESSDATA=<your_sessdata>
BILIBILI_BILI_JCT=<your_bili_jct>
BILIBILI_DEDEUSERID=<your_dedeuserid>

Cookie 获取提醒

请只从你自己的 Bilibili 登录会话中获取 Cookie。不同浏览器的开发者工具界面会变化，具体步骤请以浏览器实际界面为准。

不要把 Cookie 发给他人，不要粘贴到公开聊天、Issue、PR、README、日志或测试文件。

安全须知

• Cookie 只应保存在本地配置、环境变量或 .env 中。
• .env 已被 .gitignore 排除，但仍要避免提交。
• Cookie 泄露后应立即在 Bilibili 账号侧失效旧登录状态。
• 本项目不会把 Cookie 上传到除 Bilibili 官方 API 以外的第三方服务。

---

🧭 该用哪个工具？

目标	推荐工具	返回重点
想让 AI 总结一个视频	get_video_info	字幕优先；无字幕时返回标题、简介、标签
只想拿完整转录文本	get_video_transcript	纯字幕文本、语言、数据来源
想查看标题、作者、播放量等结构化信息	get_video_metadata	标题、作者、时长、发布时间、标签、统计数据
想看观众反馈和热门评论	get_video_comments	热门评论、时间戳评论、可选回复
让 agent 引导用户配置 Cookie	get_credential_setup_instructions	安全配置步骤、推荐命令、注意事项
检查 Cookie 是否已配置/登录	check_bilibili_credentials	configured、source、logged_in、next_steps

💡 工具调用示例

AI 客户端会自动将你的自然语言意图转换为对应的 JSON 调用。

get_credential_setup_instructions

适合：agent 安装 MCP server 后，引导用户完成 Cookie 配置。

请求示例：

{
  "name": "get_credential_setup_instructions",
  "arguments": {}
}

返回内容：推荐配置命令、全局安装命令、所需 Cookie 字段和安全提醒；不会返回任何 Cookie 值。

check_bilibili_credentials

适合：检查当前环境是否已配置 Cookie，以及是否处于登录状态。

请求示例：

{
  "name": "check_bilibili_credentials",
  "arguments": {}
}

返回内容：configured、source（env / global_config / none）、logged_in 和 next_steps；不会返回任何 Cookie 值。

get_video_transcript

适合：需要把视频内容交给 AI 做摘要、笔记、问答或知识整理。

请求示例：

{
  "name": "get_video_transcript",
  "arguments": {
    "bvid_or_url": "https://www.bilibili.com/video/BV1xx411c7mD",
    "preferred_lang": "zh-Hans",
    "fallback_to_description": false
  }
}

返回内容：bvid、title、language、transcript（按行合并）、data_source（subtitle 或 description）。

默认无字幕时返回 SUBTITLE_UNAVAILABLE。如需降级，设置 fallback_to_description: true。

get_video_metadata

适合：想快速了解视频基本信息，不需要字幕或评论内容。

请求示例：

{
  "name": "get_video_metadata",
  "arguments": {
    "bvid_or_url": "BV1xx411c7mD"
  }
}

返回内容：bvid、title、author、duration、pubdate / pubdate_timestamp、description、tags 和 stats（播放、点赞、投币、收藏、分享、评论、弹幕）。

get_video_info

适合：让 AI 总结视频核心内容——会优先尝试字幕，无字幕时回退到简介和标签。

请求示例：

{
  "name": "get_video_info",
  "arguments": {
    "bvid_or_url": "https://www.bilibili.com/video/BV1xx411c7mD",
    "preferred_lang": "zh-Hans"
  }
}

返回内容：data_source（subtitle 或 description）、video_info（标题、描述、标签、字幕文本、发布时间）。

无字幕视频会自动降级返回描述和标签（即 data_source: "description"）。

get_video_comments

适合：想了解观众对视频的真实评价、找精彩时间点。

请求示例：

{
  "name": "get_video_comments",
  "arguments": {
    "bvid_or_url": "BV1xx411c7mD",
    "detail_level": "detailed",
    "limit": 10,
    "sort": "hot",
    "include_replies": true
  }
}

返回内容：comments[]（含 author、content、likes、timestamp、has_timestamp）、summary（总数和时间戳评论数）。

Cookie 过期或未登录可能导致评论为空。sort: "time" 可获取最新评论，include_replies: false 不返回子回复。

---

🛡️ API 限流机制

为降低触发 Bilibili 风控和接口限流的概率，已内置以下请求控制策略：

• 请求启动间隔：默认 500ms（0.5 秒），可通过 BILIBILI_RATE_LIMIT_MS 调整。
• 执行方式：对 API 请求启动做节流，避免瞬时大并发；适合本地单用户 MCP 使用。
• 重试策略：对 408、429、5xx、网络错误和超时进行最多 3 次指数退避重试。
• 超时控制：默认 10 秒，可通过 BILIBILI_REQUEST_TIMEOUT_MS 调整。

---

🛠️ 开发指南

# 1. 克隆仓库
git clone https://github.com/365903728-oss/bilibili-mcp.git
cd bilibili-mcp

# 2. 安装依赖包
npm install

# 3. 运行测试
npm test

# 4. 编译 TypeScript
npm run build

# 5. 启动监听与实时编译
npm run watch

常用命令：

命令	用途
npm run build	编译 TypeScript 到 dist/
npm test	运行 Vitest 单元测试
npm run watch	开发时持续编译
npm start	运行已编译的 stdio MCP server
npm pack --dry-run	检查 npm 包会包含哪些文件

本地调试说明：

• MCP server 的入口是 dist/index.js，CLI 入口是 dist/cli.js；修改源码后先运行 npm run build。
• 启动 stdio MCP server 后，stdout 必须保留给 MCP 协议数据；调试日志和错误信息应写到 stderr，因此本项目使用 console.error 输出运行日志。
• 不要在测试、日志、示例或提交内容中写入真实 Cookie。需要验证凭证时，使用 npx -y @xzxzzx/bilibili-mcp check 或本地环境变量。

---

⚖️ 安全性与免责声明

⚠️ 重要：使用本工具即代表您同意以下条款

• 非官方项目：Bilibili（哔哩哔哩）是哔哩哔哩公司的注册商标。本项目是第三方开源辅助工具，不隶属于 Bilibili，也不代表 Bilibili 官方。
• 使用边界：本项目仅供个人学习、辅助阅读和内容理解使用。请遵守 Bilibili 用户协议、robots/接口访问规则和当地法律法规；不要用于商业剥削、大规模抓取、绕过权限或其他滥用场景。
• 账号风险：所有请求均由用户本机发起。高频调用、异常访问模式、Cookie 泄露或账号自身状态可能触发风控、限流或账号异常；相关后果由使用者自行承担。
• Cookie 安全：不要把真实 Cookie 写入 MCP 客户端配置、公开聊天、Issue、PR、README、日志或测试文件。建议使用本项目的本机凭证配置、运行环境变量或本地 .env 管理 Cookie；Cookie 泄露后应立即在 Bilibili 账号侧失效旧登录状态。
• 隐私说明：本项目不会把 Cookie 上传到除 Bilibili 官方接口以外的第三方服务。凭证仅在本机按用户选择的方式保存或读取；当前本地配置文件不承诺系统级加密，请自行保护设备、账号和配置文件访问权限。

许可证

本项目基于 GNU General Public License v3.0 开源。使用、复制、修改和分发本项目时，请遵守 GPL-3.0 的许可要求。

---

🛠️ 开发过程

本项目是一个典型的 AI 协同开发的结晶，完整经历了从原型到完善的过程：

1. 初版生成：由 Claude Code (搭载 GLM-4.7 模型) 快速搭建核心架构与基础逻辑。
2. 调试与优化：在 Antigravity 环境下，利用 Claude 和 Gemini 模型进行深度的 Bug 修复与功能增强，确保了字幕提取与评论分析的稳定性。
3. 迭代与扩展：由 Codex 进行架构决策与计划分解，Claude Code 接入 DeepSeek 模型执行实现；目前覆盖 30+ AI 客户端的 MCP 接入配置、6 个 MCP 工具、124 个单元测试。

---

💬 反馈与建议

如果您在使用过程中遇到任何问题，或者有好的功能建议，欢迎通过以下方式联系：

• 提交 Issue：GitHub Issues —— 推荐方式，我会定期查看并回复。
• 项目讨论：在 GitHub Discussions 中交流。

感谢您的支持！