bilitrack

bilitrack

bilitrack follows people and content on Bilibili: look a user up, see what they have posted lately — videos, dynamics, and articles — check who they follow, and read the comment threads under a video, dynamic, or article, including subtitle text for a video when you ask for it. Everything is read from Bilibili's public web API.

This package is a clean-room rebuild of the 12-tool BiliStalkerMCP tool list, written fresh from its public README spec.

How it talks to the service

Each tool maps onto a public endpoint under https://api.bilibili.com/x/... and returns that endpoint's data payload:

# Optional: a logged-in session raises limits and unlocks gated reads.
export SESSDATA="your SESSDATA cookie value"
export BILI_JCT="your bili_jct cookie value (optional)"
export BUVID3="your buvid3 cookie value (optional)"
# Optional override (default: https://api.bilibili.com)
export BILIBILI_API_URL="https://api.bilibili.com"

The cookies are genuinely optional. With none set, requests go out cookieless, which Bilibili accepts for most public reads — nothing fails just because SESSDATA is missing. When the API answers with a non-zero code, the call fails with that code and message; an upstream HTTP error is reported with its status and a body excerpt.

Username resolution: tools take user_id_or_username. A numeric value is used as the user's mid directly; anything else is resolved through user search and only an exact username match is accepted — a near match is an error, not a guess.

Subtitle simplification: with fetch_subtitles set, get_video_detail uses the player API to list subtitle tracks and returns either the track metadata (subtitle_scope: "metadata") or the joined text of the selected track (by subtitle_lang, or the first track), truncated to subtitle_max_chars when given. It does not stitch multi-part or AI-generated tracks the way a full player client would.

Install

npx @reneturcios/bilitrack search_users '{"keyword":"example"}'

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/bilitrack

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.

CLI

The CLI mirrors the tools: one subcommand per tool, taking its arguments as a single JSON object.

bilitrack search_users '{"keyword":"example","limit":5}'
bilitrack get_user_info '{"user_id_or_username":"12345"}'
bilitrack get_user_snapshot '{"user_id_or_username":"example"}'
bilitrack get_user_videos '{"user_id_or_username":"12345","page":2}'
bilitrack get_video_detail '{"bvid":"BV1xx411c7mD","fetch_subtitles":true,"subtitle_lang":"zh-CN"}'
bilitrack get_content_comments '{"content_type":"video","content_id":"12345","sort":"hot"}'
bilitrack --version

Exit codes: 0 on success, 1 on an API or validation error (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/bilitrack mcp

MCP client configuration:

{
  "mcpServers": {
    "bilitrack": {
      "command": "npx",
      "args": ["-y", "@reneturcios/bilitrack", "mcp"],
      "env": { "SESSDATA": "your cookie value (optional)" }
    }
  }
}

Tools

All ID parameters are strings in these schemas.

Tool	Input	What it does
search_users	keyword (required), limit	Search Bilibili users by keyword.
get_user_snapshot	user_id_or_username (required), video_limit, dynamic_limit, article_limit	Get a combined snapshot of a Bilibili user: profile, videos, dynamics, and articles.
get_user_info	user_id_or_username (required)	Get profile information for a Bilibili user.
get_user_videos	user_id_or_username (required), page, limit	List a Bilibili user's videos, paged.
search_user_videos	user_id_or_username (required), keyword (required), page, limit	Search within a Bilibili user's videos by keyword.
get_video_detail	bvid (required), fetch_subtitles, subtitle_scope, subtitle_page, subtitle_cid, subtitle_mode, subtitle_lang, subtitle_max_chars	Get detail for a Bilibili video by BVID, optionally fetching subtitles.
get_user_dynamics	user_id_or_username (required), cursor, limit, dynamic_type	List a Bilibili user's dynamics (feed posts), paged by cursor.
get_user_articles	user_id_or_username (required), page, limit	List a Bilibili user's articles, paged.
get_article_content	article_id (required; numeric or cv-prefixed)	Get the full content of a Bilibili article.
get_user_followings	user_id_or_username (required), page, limit	List accounts a Bilibili user follows, paged.
get_content_comments	content_type (required), content_id (required), cursor, limit, sort	List comments on a Bilibili video, dynamic, or article.
get_content_comment_replies	content_type (required), content_id (required), root_rpid (required), page, limit	List replies under one root comment on Bilibili content.

content_type accepts video, article, dynamic, audio, album, course, or a numeric Bilibili reply type as a string.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.