Bili Stalker MCP

What is Bili Stalker MCP about?

Bili Stalker MCP is an MCP server and CLI utility that retrieves comprehensive data about a specific Bilibili creator. It starts from a UID or username and returns structured information such as profile details, recent videos, dynamics, articles, subtitles, and the user's followings, enabling downstream AI agents to perform deep content analysis.

How to use Bili Stalker MCP?

1. Installation – Install the PyPI package:

   pip install bili-stalker-mcp
   

2. Run as a server – Start the stdio‑based MCP server with:

   bili-stalker-mcp serve
   

   (or simply bili-stalker-mcp which defaults to server mode).
3. CLI queries – Use the bundled CLI for one‑off calls without a persistent server:

   bili-stalker-mcp call get_user_snapshot --args '{"user_id_or_username":"12345","video_limit":5}' --pretty
   

   The tools sub‑command lists all available tools and their schemas.
4. Configuration – Provide Bilibili authentication via environment variables (SESSDATA, BILI_JCT, BUVID3) or a cookie file (BILI_COOKIE_FILE). Optional safe‑refresh can be enabled with BILI_ENABLE_COOKIE_REFRESH=true and a refresh‑token file.
5. Docker – Build and run the image:

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

Key Features

• 12 ready‑made MCP tools covering user search, snapshots, videos, dynamics, articles, comments, followings, and subtitle extraction.
• Concurrent fetching in get_user_snapshot for minimal latency.
• Fine‑grained subtitle control (subtitle_scope, subtitle_mode, language selection, max characters).
• Automatic cookie refresh (optional, file‑based, lock‑protected).
• Risk‑aware request jitter to mitigate Bilibili anti‑crawling limits.
• Proxy support via BILI_PROXY for unstable network environments.
• Docker image for isolated execution.
• Comprehensive CLI with doctor diagnostics, JSON schema discovery, and pretty‑print output.
• Skill bundle (skills/bili-content-analysis) that can be dropped into an AI‑agent project for a full analysis workflow.

Use Cases

• AI‑driven creator profiling – agents retrieve a creator’s latest content and generate summaries or sentiment reports.
• Automated market research – monitor competitors’ video performance, dynamics trends, and follower growth.
• Subtitle harvesting – collect multilingual subtitles for downstream speech‑to‑text or translation pipelines.
• Content moderation tooling – fetch comments and replies for automated toxicity analysis.
• Academic research – gather structured datasets of Bilibili dynamics and articles for social‑media studies.

FAQ

• Do I need a Bilibili account? Yes, a logged‑in session (SESSDATA) is required for most endpoints; some public tools work without it.
• Can I run the server without installing Python? Use the provided Docker image which contains everything needed.
• How are rate limits handled? The client adds adaptive jitter and respects 412/429/403 responses; optional jitter settings can be tuned via environment variables.
• What if my cookie expires? Enable safe cookie refresh (BILI_ENABLE_COOKIE_REFRESH=true) and provide a refresh‑token file; the server will automatically refresh SESSDATA.
• Is the project compatible with other MCP clients? Yes, the server follows the standard MCP JSON schema and can be invoked over stdio by any compliant client.
• Where are the tools documented? Run bili-stalker-mcp tools to list all tools; bili-stalker-mcp tools <tool> shows the full schema and argument details.

BiliStalkerMCP

Bilibili MCP Server for Specific User Analysis

BiliStalkerMCP is a Bilibili MCP server and command-line tool built on Model Context Protocol (MCP), designed for AI agents that need to analyze a specific Bilibili user or creator.

It is optimized for workflows that start from a target uid or username, then retrieve that user's profile, videos, dynamics, articles, subtitles, and followings with structured tools.

If you are searching for a Bilibili MCP server, a Bilibili Model Context Protocol server, or an MCP server for tracking and analyzing a specific Bilibili user, this repository is designed for that use case.

English | 中文说明

🚀 Quick Start

🤖 Method 1: Let your AI Agent configure it (Recommended)

Copy and send the following to Claude Code, Codex, or other AI agents:

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).

---

🛠️ Method 2: Manual Configuration (MCP Clients)

Configuration paths and syntax may vary across different clients.

1. Run the PyPI release directly

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

2. Run from cloned source

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

Then replace /path/to/BiliStalkerMCP below with your actual absolute path:

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

Prefer uv run --directory ... for faster local updates when PyPI release propagation is delayed. You can still use uvx bili-stalker-mcp for quick one-off usage.

Auth: Provide SESSDATA directly, or put it in BILI_COOKIE_FILE. Obtain it from Browser DevTools (F12) > Application > Cookies > .bilibili.com.

Method 3: Command-line queries

From this checkout, use the CLI to query any of the 12 tools without configuring an MCP client or starting a persistent server:

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 lists names and descriptions; tools TOOL returns the full MCP schema, including required arguments, defaults, and limits. call TOOL accepts the same names and JSON arguments as the MCP tools. IDs declared as strings in the schema must remain quoted, including numeric UIDs and long article/dynamic IDs. doctor prints JSON diagnostics for credential sources, refresh configuration, proxy settings, and dependency versions. By default it does not use the network, change credential files, or print credential values. doctor --network adds a TCP connectivity check; it does not verify login or an API response.

For larger arguments or to avoid shell quoting issues, read a UTF-8 JSON file or pipe a JSON object through stdin:

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 -

Set the environment variables below in the calling shell, for example $env:BILI_COOKIE_FILE = 'D:\BiliStalkerSecrets\bili-cookie.txt' in PowerShell. An MCP client's env configuration is not automatically inherited by a separate terminal. The CLI uses the same credential, refresh, proxy, and rate-limit behavior as MCP. Help, version, and tool discovery do not require login credentials.

If the checkout already has a .env file, load it explicitly for the command; neither the CLI nor a plain uv run automatically loads it:

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

Successful queries write one UTF-8 JSON value to stdout; logs and errors go to stderr. Redirect stdout to save a result. Exit codes are 0 for success, 1 for query/configuration failures (including an unhealthy doctor report), 2 for invalid commands or arguments, and 130 for interruption. Query and argument failures end with a JSON error object on stderr; risk-control errors retain code and retry_after. A snapshot can succeed with incomplete sections: inspect its errors field before interpreting it.

uv run python -m bili_stalker_mcp ... accepts the same arguments. With an installed package, use bili-stalker-mcp ... directly. Running without a subcommand still starts the MCP stdio server; bili-stalker-mcp serve makes that explicit.

Environment Variables

Key	Req	Description
SESSDATA	Conditional	Bilibili session token; required unless BILI_COOKIE_FILE provides it.
BILI_JCT	No	CSRF protection token.
BUVID3	No	Hardware fingerprint (reduces rate-limiting risk).
BILI_COOKIE_FILE	No	Path to a plain Cookie file.
BILI_REFRESH_TOKEN_FILE	No	Path to the separate refresh-token file; never set the token through an environment variable.
BILI_ENABLE_COOKIE_REFRESH	No	true enables safe automatic refresh; default: false.
BILI_COOKIE_REFRESH_CHECK_INTERVAL_SECONDS	No	Refresh-check interval; default: 21600, minimum: 60.
BILI_PROXY	No	Route all upstream requests (bilibili_api and the built-in HTTP clients) through this proxy. Recommended when the system proxy is not picked up automatically or DNS resolution for Bilibili hosts is unstable. If the proxy is unreachable at startup, the server falls back to direct connections and logs a warning.
BILI_REQUEST_JITTER_MODE	No	Upstream jitter behavior: adaptive (default; sleeps only without a configured login or after recent 412/429/403), always, never.
BILI_REQUEST_JITTER_MIN_MS / BILI_REQUEST_JITTER_MAX_MS	No	Jitter sleep range; default: 200–1200.
BILI_REQUEST_JITTER_BUDGET_MS	No	Total jitter sleep allowed per tool call; default: 500.
BILI_RISK_PRESSURE_WINDOW_SECONDS	No	How long a 412/429/403 keeps adaptive jitter engaged; default: 300.
BILI_LOG_LEVEL	No	DEBUG, INFO (Default), WARNING.
BILI_TIMEZONE	No	Output time zone for formatted timestamps (default: Asia/Shanghai).

Optional Safe Cookie Refresh

Automatic refresh is disabled by default. Enable it only when the Cookie file and refresh-token file are existing, readable, writable regular files. The Cookie file may contain only ordinary Cookie values (SESSDATA, bili_jct, buvid3, buvid4, and DedeUserID); the refresh token belongs only in its own file.

{
  "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"
}

When refresh is enabled, do not set SESSDATA, BILI_JCT, or DEDEUSERID in the environment: those rotating values must come from the Cookie file so a restart cannot reload stale credentials. BUVID3 and BUVID4 may still be provided through the environment. Refresh checks are rate-limited, and concurrent MCP calls or server processes sharing these files use one refresh lock. Pending confirmation is recovered before another refresh. The .bili-cookie-refresh.lock sidecar may remain on disk between runs.

For a quicker initial setup, copy the complete Cookie header value from a Bilibili browser request and ac_time_value from Local Storage, then run:

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

For a PyPI-only invocation without cloning this repository:

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

The script hides both pasted values, refuses directories inside the repository and existing credential files, and prints only a non-secret MCP env block. Do not paste an entire cURL command: paste only the value after its cookie: header.

Local Verification

All verification commands use mocks and do not require Bilibili credentials:

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

Available Tools

Tool	Capability	Parameters
search_users	Lightweight user candidates with numeric UIDs	keyword, limit
get_user_snapshot	One-call overview: profile + recent videos/dynamics/articles fetched concurrently	user_id_or_username, video_limit, dynamic_limit, article_limit (0 skips a section)
get_user_info	Rich profile: level, official title, VIP, live room, ban status, following/follower, total video views/article views/likes (needs bili_jct)	user_id_or_username
get_user_videos	Lightweight video list	user_id_or_username, page, limit
search_user_videos	Keyword search in one user's video list	user_id_or_username, keyword, page, limit
get_video_detail	Full video detail + optional subtitles	bvid, fetch_subtitles (default: false), subtitle_scope (single/all, default: single), subtitle_page, subtitle_cid, subtitle_mode (smart/full/minimal), subtitle_lang (default: auto), subtitle_max_chars
get_user_dynamics	Structured dynamics with image metadata and cursor pagination	user_id_or_username, cursor, limit, dynamic_type
get_user_articles	Lightweight article list	user_id_or_username, page, limit
get_article_content	Full article markdown content	article_id
get_user_followings	Subscription list analysis	user_id_or_username, page, limit
get_content_comments	Comments for a video, article, or dynamic (including images and note metadata)	content_type, content_id, cursor, limit, sort
get_content_comment_replies	Full sub-replies for a video, article, or dynamic comment	content_type, content_id, root_rpid, page, limit

When starting from a username, call search_users once and reuse the returned numeric UID for subsequent tools. Implicit username resolution accepts exact matches only; it does not silently select the first similar search result.

Comment pictures contain the original image URLs. Regular long comments retain the full text returned by Bilibili. Note-style comments may contain only a preview; use the returned note.cvid with get_article_content to retrieve the full note. For video comments, pass content_type="video" and a BVID, AV number, or video URL as content_id. Use a top-level comment's rpid as root_rpid when fetching its complete reply thread.

Dynamic Filtering (dynamic_type)

• ALL (default): Text, Draw, Reposts, and Video dynamics.
• ALL_RAW: Unfiltered (additionally includes Articles and unknown types).
• VIDEO, ARTICLE, DRAW, TEXT: Specific category filtering.
• REVIEW: Recognized five-slot rating cards only. Each result exposes review.rating (filled stars, 0-5), review.title, review.text, cover and jump URLs, plus the source score description when available. This filter does not independently classify whether the rated title is an anime.

Each dynamic item includes an images list. Every image contains url, width, and height; invalid URLs are omitted, and unavailable dimensions are null. image_count always equals the number of returned images. Reposts expose the same fields under origin.images and origin.image_count. Non-image dynamics return an empty images list.

Pagination: Responses include next_cursor. Pass this to subsequent requests for seamless scrolling.

Subtitle Modes (get_video_detail)

Page scope is independent of language/track mode. The default subtitle_scope="single" queries only P1 in both smart and full. A full URL with p=2 selects P2; alternatively pass subtitle_page=2 or a subtitle_cid belonging to this video. Page/CID must be positive integers, and the two explicit selectors are mutually exclusive. Conflicting URL/explicit selections, missing pages, and foreign CIDs return invalid_subtitle_selection without falling back to another page.

For all pages, explicitly set subtitle_scope="all" with a BVID or URL without p. It cannot be combined with page/CID selectors or URL p. All scope still scans every page's subtitle metadata; single scope queries only the selected page. Default behavior change: callers relying on the previous all-page scan must add subtitle_scope="all".

• smart (default when fetch_subtitles=true): download one best-matched track within the selected scope.
• full: download every language track within the selected scope (higher cost).
• minimal: skip subtitle metadata and subtitle text fetching.

In smart mode, subtitle_lang can request a language (for example en-US); auto uses built-in priority fallback. subtitle_max_chars caps returned subtitle text size to avoid token explosion.

Subtitle text is returned once via full_text; tracks carry metadata only (text is always empty). In full mode with multiple tracks, each segment in full_text is prefixed with a [language · part] label.

Video detail includes owner: {mid, name, face} (or null), duration (upstream total seconds across all parts), pic, tname, videos, and ctime (Unix seconds). Missing metadata is null; pages[] keeps cid/page/part/duration with each part's duration in seconds. mid and uid both identify a Bilibili user. An empty tags array can also mean the detail source omitted tags.

selected_language is set only in smart mode; full mode returns null and lists languages in tracks[].lan. truncated=true means the character budget cut or dropped subtitle text. A track can remain in tracks when its download fails; check errors and full_text. Subtitle text has no timecodes.

subtitles.scope contains mode, target_page, total_pages, returned_pages, and summary, distinguishing the selected scope from pages actually represented in the returned text and stating how many pages have no returned text. returned_pages means at least one text character was returned for that page; it does not guarantee completeness, so check errors and truncated. Video pages[] always keeps the complete list. With subtitles disabled, scope is null and selectors do not apply. minimal validates the selected range but returns no text pages and makes no subtitle API calls.

Bundled Skill

The repository ships a ready-to-use AI agent skill in 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

What It Does

Guides compatible AI agents (Gemini, Claude, etc.) through a structured 6-step workflow for deep Bilibili content analysis using MCP tools or the CLI:

1. Clarify target and scope (uid / bvid / keyword).
2. Collect evidence — lightweight lists first, heavy detail only for high-value items.
3. Reconstruct source structure before interpreting (timeline, chapters, speakers).
4. Analyze — facts, logic chain, assumptions, themes, and shifts.
5. Retain anchors — uid, bvid, article_id, timestamps, key source snippets.
6. Handle failures — state blockers explicitly, stop speculation.

Usage

Copy the bili-content-analysis folder into your project's skill directory:

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

The agent will automatically activate the skill when user requests involve Bilibili creator tracking, transcript interpretation, timeline reconstruction, or content analysis.

Development

# 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

Release (Maintainers)

Credentials: The release script uses UV_PUBLISH_TOKEN when set; otherwise it reads the matching [pypi] or [testpypi] token from $HOME\.pypirc. Twine is invoked transiently through uvx only for package metadata validation and is not a project dependency.

# 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

Runs via stdio transport. No ports exposed.

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

Troubleshooting

• 412 Precondition Failed: Bilibili anti-crawling system triggered. Refresh SESSDATA or provide BUVID3.
• Cloud IPs: Highly susceptible to blocking; local execution is recommended.
• Long ~20s stalls or DNS timeouts on upstream calls: configure BILI_PROXY. bilibili_api's curl_cffi client ignores system and environment proxies unless an explicit proxy is set.

Upstream Dependency Note

bilibili-api-python is pinned to ==17.4.2. Its upstream repository has been permanently shut down following a legal notice from Bilibili, so no further maintenance or fixes can be expected from that project. Additionally, the package is licensed GPL-3.0-or-later, which means its source cannot be vendored or forked into this MIT-licensed repository.

The mitigation path is incremental migration of the remaining SDK-backed endpoints (user info, video lists, subtitles in video details, dynamics, articles) onto this project's own raw HTTP stack (SharedRawHttpClient), which already serves comments, followings, relation stats, and video details without subtitles independently of the SDK. The pin should be kept exact so installs never pick up an unknown future version.

License

MIT

Disclaimer: For personal research and learning only. Bulk profiling, harassment, or commercial surveillance is prohibited.

---

This project is built and maintained with the help of AI.