222wcnm-bilistalkermcp

BiliStalkerMCP

面向特定用户分析的 Bilibili MCP 服务

BiliStalkerMCP 是一个基于 Model Context Protocol (MCP) 构建的 Bilibili MCP 服务和命令行工具，专为需要分析特定 Bilibili 用户或创作者的 AI Agent 设计。

它针对以下工作流进行了优化：从目标 UID 或用户名开始，然后通过结构化工具获取该用户的个人资料、视频、动态、专栏、字幕和关注列表。

如果你正在寻找 Bilibili MCP 服务、Bilibili Model Context Protocol 服务，或用于跟踪和分析特定 Bilibili 用户的 MCP 服务，本仓库正是为此场景设计的。

English | 中文说明

🚀 快速开始

🤖 方法 1：让你的 AI Agent 配置（推荐）

复制并发送以下内容给 Claude Code、Codex 或其他 AI Agent：

Check the current client environment's MCP configuration standards, then configure 222wcnm/BiliStalkerMCP as an available MCP server. If needed, ask whether to configure it globally or per-project, and prompt me for required Bilibili environment variables (e.g. SESSDATA).

---

🛠️ 方法 2：手动配置（MCP 客户端）

不同客户端的配置路径和语法可能有所不同。

1. 直接运行 PyPI 发行版

{
  "mcpServers": {
    "bilistalker": {
      "command": "uvx",
      "args": ["bili-stalker-mcp"],
      "env": {
        "SESSDATA": "required_sessdata",
        "BILI_JCT": "optional_jct",
        "BUVID3": "optional_buvid3"
      }
    }
  }
}

2. 从克隆的源码运行

git clone https://github.com/222wcnm/BiliStalkerMCP.git
cd BiliStalkerMCP

然后将下方的 /path/to/BiliStalkerMCP 替换为你的实际绝对路径：

{
  "mcpServers": {
    "bilistalker": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/BiliStalkerMCP", "bili-stalker-mcp"],
      "env": {
        "SESSDATA": "required_sessdata",
        "BILI_JCT": "optional_jct",
        "BUVID3": "optional_buvid3"
      }
    }
  }
}

如果 PyPI 发行版的同步发布有所延迟，建议使用 uv run --directory ...，以便更快地进行本地更新。 你仍可使用 uvx bili-stalker-mcp 快速进行一次性使用。

身份验证：直接提供 SESSDATA，或将其放入 BILI_COOKIE_FILE。可通过浏览器开发者工具（F12）> Application > Cookies > .bilibili.com 获取。

方法 3：命令行查询

在此检出目录中，使用 CLI 查询 12 个工具中的任意一个，无需配置 MCP 客户端或启动常驻服务：

uv run bili-stalker-mcp --help
uv run bili-stalker-mcp doctor
uv run bili-stalker-mcp doctor --network
uv run bili-stalker-mcp tools
uv run bili-stalker-mcp tools get_user_snapshot --pretty
uv run bili-stalker-mcp call search_users --args '{"keyword":"username","limit":5}'
uv run bili-stalker-mcp call get_user_snapshot --args '{"user_id_or_username":"12345","video_limit":5,"dynamic_limit":5,"article_limit":0}' --pretty
uv run bili-stalker-mcp call get_video_detail --args '{"bvid":"BV1xx411c7mD","fetch_subtitles":true,"subtitle_max_chars":12000}'
uv run bili-stalker-mcp call get_video_detail --args '{"bvid":"https://www.bilibili.com/video/BV16cj96FEmw?p=2","fetch_subtitles":true}'
uv run bili-stalker-mcp call get_video_detail --args '{"bvid":"BV1xx411c7mD","fetch_subtitles":true,"subtitle_scope":"all","subtitle_mode":"full"}'

tools 会列出名称和说明；tools TOOL 会返回完整的 MCP 架构，包括必需参数、默认值和限制。call TOOL 接受与 MCP 工具相同的名称和 JSON 参数。架构中声明为字符串的 ID 必须保留引号，包括数字 UID 以及较长的文章 ID 或动态 ID。 doctor 会输出 JSON 诊断信息，包括凭据来源、刷新配置、代理设置和依赖版本。默认情况下，它不会使用网络、修改凭据文件或输出凭据值。doctor --network 会额外检查 TCP 连通性；它不会验证登录状态或 API 响应。

对于较大的参数，或为避免 shell 引号问题，可以读取 UTF-8 JSON 文件，或通过 stdin 传入 JSON 对象：

uv run bili-stalker-mcp call get_user_snapshot --args-file args.json --pretty
@{ user_id_or_username = "12345"; limit = 5 } | ConvertTo-Json -Compress | uv run bili-stalker-mcp call get_user_videos --args-file -

在调用命令的 shell 中设置下方的环境变量，例如在 PowerShell 中设置 $env:BILI_COOKIE_FILE = 'D:\BiliStalkerSecrets\bili-cookie.txt'。 MCP 客户端的 env 配置不会自动传递给单独的终端。CLI 与 MCP 使用相同的凭据、刷新、代理和速率限制行为。帮助、版本和工具发现无需登录凭据。

如果检出目录中已有 .env 文件，请在运行命令时显式加载；CLI 和普通的 uv run 都不会自动加载该文件：

uv run --env-file .env bili-stalker-mcp call get_user_info --args '{"user_id_or_username":"12345"}'

查询成功时会向 stdout 写入一个 UTF-8 JSON 值；日志和错误会输出到 stderr。将 stdout 重定向即可保存结果。退出码如下：0 表示成功，1 表示查询或配置失败（包括 doctor 报告不健康），2 表示命令或参数无效，130 表示中断。查询和参数错误会在 stderr 末尾输出 JSON error 对象；风控错误会保留 code 和 retry_after。快照可能会在部分内容不完整的情况下成功：请检查其 errors 字段后再进行解读。

uv run python -m bili_stalker_mcp ... 接受相同的参数。安装软件包后，可直接使用 bili-stalker-mcp ...。不带子命令运行仍会启动 MCP stdio 服务；bili-stalker-mcp serve 则会明确指定这一操作。

环境变量

键	必需	说明
SESSDATA	有条件	Bilibili 会话令牌；除非由 BILI_COOKIE_FILE 提供，否则必需。
BILI_JCT	否	CSRF 防护令牌。
BUVID3	否	硬件指纹（可降低触发速率限制的风险）。
BILI_COOKIE_FILE	否	普通 Cookie 文件的路径。
BILI_REFRESH_TOKEN_FILE	否	单独的刷新令牌文件路径；切勿通过环境变量设置该令牌。
BILI_ENABLE_COOKIE_REFRESH	否	设为 true 可启用安全的自动刷新；默认值：false。
BILI_COOKIE_REFRESH_CHECK_INTERVAL_SECONDS	否	刷新检查间隔；默认值：21600，最小值：60。
BILI_PROXY	否	通过此代理路由所有上游请求（bilibili_api 和内置 HTTP 客户端）。当系统代理未被自动识别，或 Bilibili 主机的 DNS 解析不稳定时，建议设置此项。如果服务启动时无法连接代理，则会回退到直接连接并记录警告。
BILI_REQUEST_JITTER_MODE	否	上游抖动行为：adaptive（默认；仅在未配置登录信息或近期出现 412/429/403 时休眠）、always、never。
BILI_REQUEST_JITTER_MIN_MS / BILI_REQUEST_JITTER_MAX_MS	否	抖动休眠范围；默认值：200–1200。
BILI_REQUEST_JITTER_BUDGET_MS	否	每次工具调用允许的总抖动休眠时长；默认值：500。
BILI_RISK_PRESSURE_WINDOW_SECONDS	否	412/429/403 使自适应抖动保持启用的时长；默认值：300。
BILI_LOG_LEVEL	否	DEBUG、INFO（默认）、WARNING。
BILI_TIMEZONE	否	格式化时间戳的输出时区（默认值：Asia/Shanghai）。

可选的安全 Cookie 刷新

默认情况下会禁用自动刷新。仅当 Cookie 文件和刷新令牌文件均已存在，且是可读、可写的常规文件时，才启用此功能。Cookie 文件中只能包含普通 Cookie 值（SESSDATA、bili_jct、buvid3、buvid4 和 DedeUserID）；刷新令牌只能存放在其专用文件中。

{
  "BILI_COOKIE_FILE": "/secure/bilibili-cookie.txt",
  "BILI_REFRESH_TOKEN_FILE": "/secure/bilibili-refresh-token.txt",
  "BILI_ENABLE_COOKIE_REFRESH": "true",
  "BILI_COOKIE_REFRESH_CHECK_INTERVAL_SECONDS": "21600"
}

启用刷新后，不要在环境中设置 SESSDATA、BILI_JCT 或 DEDEUSERID：这些会轮换的值必须从 Cookie 文件读取，以免重启时重新加载过期凭据。仍可通过环境提供 BUVID3 和 BUVID4。刷新检查有频率限制；共享这些文件的并发 MCP 调用或服务进程会共用一个刷新锁。下次刷新前会先恢复待确认状态。.bili-cookie-refresh.lock 旁文件可能会在运行之间保留在磁盘上。

若要更快完成初始设置，请从 Bilibili 浏览器请求中复制完整的 Cookie 标头值，并从 Local Storage 复制 ac_time_value，然后运行：

uv run bili-stalker-cookie-setup --directory D:\BiliStalkerSecrets

若仅通过 PyPI 调用而不克隆此仓库：

uvx --from bili-stalker-mcp bili-stalker-cookie-setup --directory D:\BiliStalkerSecrets

该脚本会隐藏粘贴的两个值，拒绝使用仓库内的目录和已有凭据文件，并且只输出不含机密信息的 MCP env 块。请勿粘贴完整的 cURL 命令：只粘贴 cookie: 标头后的值。

本地验证

所有验证命令均使用模拟对象，无需 Bilibili 凭据：

uv run pytest -q tests/test_credentials.py tests/test_cookie_refresh.py tests/test_tool_contract.py
uv run pytest -q
uv run black --check bili_stalker_mcp tests scripts
uv run isort --check-only bili_stalker_mcp tests scripts
uv run flake8 bili_stalker_mcp tests scripts
uv run mypy bili_stalker_mcp

可用工具

工具	功能	参数
search_users	通过数值 UID 查找精简的用户候选列表	keyword、limit
get_user_snapshot	一次调用获取概览：并发获取个人资料和近期视频／动态／文章	user_id_or_username、video_limit、dynamic_limit、article_limit（设为 0 可跳过相应部分）
get_user_info	详细个人资料：等级、官方头衔、VIP、直播间、封禁状态、关注数／粉丝数、视频总播放量／文章浏览量／点赞数（需要 bili_jct）	user_id_or_username
get_user_videos	精简的视频列表	user_id_or_username、page、limit
search_user_videos	在某个用户的视频列表中按关键词搜索	user_id_or_username、keyword、page、limit
get_video_detail	完整视频详情及可选字幕	bvid、fetch_subtitles（默认：false）、subtitle_scope（single／all，默认：single）、subtitle_page、subtitle_cid、subtitle_mode（smart／full／minimal）、subtitle_lang（默认：auto）、subtitle_max_chars
get_user_dynamics	包含图片元数据并支持游标分页的结构化动态	user_id_or_username、cursor、limit、dynamic_type
get_user_articles	精简的文章列表	user_id_or_username、page、limit
get_article_content	完整的文章 Markdown 内容	article_id
get_user_followings	关注列表分析	user_id_or_username、page、limit
get_content_comments	视频、文章或动态的评论（包括图片和笔记元数据）	content_type、content_id、cursor、limit、sort
get_content_comment_replies	获取视频、文章或动态评论的完整子回复	content_type、content_id、root_rpid、page、limit

从用户名开始时，调用一次 search_users，并在后续工具调用中重复使用返回的数值 UID。隐式用户名解析只接受完全匹配；不会默默选用第一个相似的搜索结果。

评论中的 pictures 包含原始图片 URL。普通长评论会保留 Bilibili 返回的完整文本。笔记类评论可能只包含预览；请使用返回的 note.cvid 调用 get_article_content 获取完整笔记。 对于视频评论，请将 content_type="video"，并将 BVID、AV 号或视频 URL 作为 content_id。获取某条顶层评论的完整回复串时，请将其 rpid 用作 root_rpid。

动态筛选（dynamic_type）

• ALL（默认）：文字、绘图、转发和视频动态。
• ALL_RAW：不过滤（还会包含专栏和未知类型）。
• VIDEO、ARTICLE、DRAW、TEXT：筛选特定类别。
• REVIEW：仅识别五档评分卡片。每个结果都会提供 review.rating（填充星数，0-5）、review.title、review.text、封面和 跳转 URL，以及可用时的来源评分描述。此筛选不会单独判断被评分的标题是否为动漫。

每个动态项都包含一个 images 列表。每张图片都包含 url、width 和 height；无效 URL 会被省略，无法获取的尺寸为 null。 image_count 始终等于返回的图片数量。转发动态会在 origin.images 和 origin.image_count 下提供相同字段。非图片动态返回空的 images 列表。

分页：响应包含 next_cursor。将其传入后续请求，即可无缝滚动浏览。

字幕模式（get_video_detail）

页面范围与语言／音轨模式相互独立。默认的 subtitle_scope="single" 在 smart 和 full 模式下都只查询 P1。带有 p=2 的完整 URL 会选择 P2； 也可以传入 subtitle_page=2，或传入属于此视频的 subtitle_cid。 页面和 CID 必须为正整数，且两个显式选择器不能同时使用。 URL 与显式选择冲突、页面不存在或 CID 属于其他视频时，会返回 invalid_subtitle_selection，不会回退到其他页面。

若要获取所有页面，请使用 BVID 或不带 p 的 URL，并显式设置 subtitle_scope="all"。 此设置不能与页面／CID 选择器或 URL p 同时使用。all 范围仍会扫描 每个页面的字幕元数据；single 范围只查询所选页面。 默认行为变更：依赖此前全页扫描行为的调用方必须添加 subtitle_scope="all"。

• smart（fetch_subtitles=true 时的默认模式）：在所选范围内下载一条匹配度最高的音轨。
• full：在所选范围内下载所有语言的音轨（成本较高）。
• minimal：跳过字幕元数据和字幕文本的获取。

在 smart 模式下，subtitle_lang 可用于指定语言（例如 en-US）； auto 会使用内置优先级回退机制。 subtitle_max_chars 会限制返回的字幕文本大小，避免令牌数量激增。

字幕文本通过 full_text 返回一次；tracks 仅包含元数据 （text 始终为空）。在包含多条音轨的 full 模式下， full_text 中每段文本前都会添加 [language · part] 标签。

视频详情包含 owner: {mid, name, face}（或 null）、duration（上游提供的 所有分 P 总秒数）、pic、tname、videos 和 ctime（Unix 秒）。缺失的元数据为 null；pages[] 会保留各分 P 的 cid/page/part/duration， 其中 duration 的单位为秒。mid 和 uid 都表示 Bilibili 用户。 tags 为空数组也可能表示详情来源未提供标签。

selected_language 仅在 smart 模式下设置；full 模式返回 null 并在 tracks[].lan 中列出语言。truncated=true 表示字符数限制导致字幕文本被截断或删除。 即使音轨下载失败，它仍可能保留在 tracks 中；请检查 errors 和 full_text。 字幕文本不含时间码。

subtitles.scope 包含 mode、target_page、total_pages、returned_pages 和 summary，用于区分所选范围与返回文本实际包含的页面，并说明有多少页面没有返回文本。 returned_pages 表示该页面至少返回了一个文本字符； 这不保证文本完整，因此请检查 errors 和 truncated。 视频 pages[] 始终保留完整列表。禁用字幕时，范围为 null，且选择器不适用。minimal 会校验所选范围，但不返回文本页面，也不会调用字幕 API。

内置技能

仓库随附了一个可直接使用的 AI Agent 技能，位于 skills/bili-content-analysis/：

skills/bili-content-analysis/
├── SKILL.md                        # Workflow & output contract
└── references/
    ├── cli.md                      # CLI discovery, queries, and error handling
    └── analysis-style.md           # Detailed writing style rules

功能

引导兼容的 AI Agent（Gemini、Claude 等）通过结构化的 6 步工作流，使用 MCP 工具或命令行深入分析 Bilibili 内容：

1. 明确目标和范围（uid / bvid / 关键词）。
2. 收集证据——先获取轻量级列表，仅对高价值内容收集详尽信息。
3. 重构来源结构后再进行解读（时间线、章节、发言者）。
4. 分析事实、逻辑链、假设、主题和变化。
5. 保留锚点——uid、bvid、article_id、时间戳、关键来源片段。
6. 处理失败——明确说明阻碍，停止推测。

使用方法

将 bili-content-analysis 文件夹复制到项目的技能目录：

<project>/.agent/skills/bili-content-analysis/

当用户请求涉及 Bilibili 创作者追踪、转录内容解读、时间线重构或内容分析时，Agent 会自动启用该技能。

开发

# Setup
git clone https://github.com/222wcnm/BiliStalkerMCP.git
cd BiliStalkerMCP
uv sync --dev

# Test
uv run pytest -q

# Integration & Performance (Requires Auth)
uv run python scripts/integration_suite.py -u <UID>
uv run python scripts/perf_baseline.py -u <UID> --tools dynamics -n 3

发布（维护者）

凭据：如果已设置 UV_PUBLISH_TOKEN，发布脚本会使用它；否则会从 $HOME\.pypirc 中读取相应的 [pypi] 或 [testpypi] 令牌。 Twine 仅通过 uvx 临时调用，用于验证软件包元数据，并非项目依赖项。

# Build + test + package metadata validation (no upload)
.\scripts\pypi_release.ps1

# Upload to TestPyPI
.\scripts\pypi_release.ps1 -TestPyPI -Upload

# Upload to PyPI
.\scripts\pypi_release.ps1 -Upload

Docker

通过 stdio 传输运行。不公开任何端口。

docker build -t bilistalker-mcp .
docker run -e SESSDATA=... bilistalker-mcp

故障排除

• 412 Precondition Failed：触发了 Bilibili 的反爬系统。刷新 SESSDATA 或提供 BUVID3。
• 云 IP：极易被封锁；建议在本地运行。
• 上游调用长时间卡顿约 20s 或发生 DNS 超时：配置 BILI_PROXY。除非显式设置代理，否则 bilibili_api 的 curl_cffi 客户端会忽略系统代理和环境代理。

上游依赖说明

bilibili-api-python 固定为 ==17.4.2。由于收到 Bilibili 的法律通知，其上游代码库已永久关闭，因此无法期待该项目提供进一步维护或修复。此外，该软件包采用 GPL-3.0-or-later 许可证，这意味着其源代码不能引入或分叉到此 MIT 许可的代码库中。

缓解方案是逐步将其余由 SDK 提供支持的端点（用户信息、视频列表、视频详情中的字幕、动态、文章）迁移到本项目自己的原始 HTTP 技术栈（SharedRawHttpClient）。该技术栈已可独立于 SDK 提供评论、关注列表、关系统计信息，以及不含字幕的视频详情。应保持精确固定该版本，以免安装时获取未知的未来版本。

许可证

MIT

免责声明：仅供个人研究和学习使用。禁止批量画像、骚扰或商业监控。

---

本项目在 AI 的帮助下构建和维护。