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}'

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": "/sec…[redacted]",
  "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_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_articl