BiliStalkerMCP by 222wcnm - MCP Server

BiliStalkerMCP

BiliStalkerMCP is an MCP server providing high-fidelity Bilibili data access for AI agents (Claude, ChatGPT).

English |

Installation

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

Configuration (Claude Desktop, Recommended)

{
  "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: Obtain SESSDATA from Browser DevTools (F12) > Application > Cookies > .bilibili.com.

Environment Variables

Key	Req	Description
`SESSDATA`	Yes	Bilibili session token.
`BILI_JCT`	No	CSRF protection token.
`BUVID3`	No	Hardware fingerprint (reduces rate-limiting risk).
`BILI_LOG_LEVEL`	No	`DEBUG`, `INFO` (Default), `WARNING`.
`BILI_TIMEZONE`	No	Output time zone for formatted timestamps (default: `Asia/Shanghai`).

Available Tools

Tool	Capability	Parameters
`get_user_info`	Profile & core statistics	`user_id_or_username`
`get_user_videos`	Lightweight video list	`user_id_or_username`, `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 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`

Dynamic Filtering (`dynamic_type`)

ALL (default): Text, Draw, and Reposts.
ALL_RAW: Unfiltered (includes Videos & Articles).
VIDEO, ARTICLE, DRAW, TEXT: Specific category filtering.

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

Subtitle Modes (`get_video_detail`)

smart (default when fetch_subtitles=true): fetch metadata for all pages, download only one best-matched subtitle track text.
full: download text for all subtitle tracks (higher cost).
minimal: skip subtitle metadata and subtitle text fetching.

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

Development

# Setup
git clone https://github.com/222wcnm/BiliStalkerMCP.git
cd BiliStalkerMCP
uv pip install -e .[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)

Prerequisite: Ensure that a .pypirc file is configured in your user home directory to provide PyPI credentials.

# Build + test + twine check (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.

License

MIT

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