BiliStalkerMCP

针对特定用户分析的Bilibili MCP服务器

BiliStalkerMCP 是一个基于 模型上下文协议 (MCP) 构建的 Bilibili MCP 服务器，专为需要分析特定 Bilibili 用户或创作者的 AI 代理设计。

它针对从目标 uid 或用户名开始，然后使用结构化工具检索该用户的个人资料、视频、动态、专栏、字幕和关注列表的工作流程进行了优化。

如果你正在寻找一个 Bilibili MCP 服务器、一个 Bilibili 模型上下文协议服务器，或者一个用于跟踪和分析特定 Bilibili 用户的 MCP 服务器，本仓库正是为此用例而设计。

English | 中文说明

安装

uvx bili-stalker-mcp
# or
pip install bili-stalker-mcp

配置（Claude Desktop，推荐）

{
  "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 获取。

环境变量

可选的安全 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

Related MCP server: MediaCrawler MCP Server

可用工具

从用户名开始时，先调用一次 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）

• smart（当 fetch_subtitles=true 时的默认值）：获取所有分集的元数据，仅下载一个最佳匹配的字幕轨道文本。

• full：下载所有字幕轨道的文本（成本较高）。

• minimal：跳过字幕元数据和字幕文本获取。

subtitle_lang 可以强制指定语言（例如 en-US）；auto 使用内置优先级回退。
subtitle_max_chars 限制返回的字幕文本大小，避免令牌爆炸。

字幕文本通过 full_text 一次性返回；tracks 仅携带元数据（text 始终为空）。在 full 模式下，如果有多个轨道，full_text 中的每个片段会以 [语言 · 部分] 标签为前缀。

捆绑技能

本仓库附带一个即用型 AI 代理技能，位于 skills/bili-content-analysis/：

skills/bili-content-analysis/
├── SKILL.md                        # Workflow & output contract
└── references/
    └── analysis-style.md           # Detailed writing style rules

功能

引导兼容的 AI 代理（Gemini、Claude 等）通过结构化的 6 步工作流程进行深度 Bilibili 内容分析：

1. 明确目标与范围（uid / bvid / 关键词）。

2. 收集证据——优先轻量级列表，仅对高价值项目进行详细分析。

3. 重构原始结构后再进行解读（时间线、章节、发言者）。

4. 分析——事实、逻辑链条、假设、主题及变化。

5. 保留锚点——uid、bvid、article_id、时间戳、关键来源片段。

6. 处理失败情况——明确说明阻塞因素，停止推测。

使用方法

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

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

当用户请求涉及B站创作者追踪、转录解读、时间线重构或内容分析时，智能体将自动激活该技能。

开发

# 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 前置条件失败：触发了B站反爬系统。请刷新 SESSDATA 或提供 BUVID3。

• 云IP：极易被屏蔽；建议本地执行。

许可证

MIT

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

本项目借助AI构建与维护。