# 222wcnm-bilistalkermcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/222wcnm/BiliStalkerMCP  
**GitHub Stars:** 9  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/222wcnm-bilistalkermcp

## Description
Track Bilibili creators and get the latest updates on videos, dynamics, and articles. Fetch user p…

## Tools
Capabilities this server exposes over MCP:

- **search_users** — keyword`, `limit
- **get_user_snapshot** — user_id_or_username`, `video_limit`, `dynamic_limit`, `article_limit` (0 skips a section)
- **get_user_info** — user_id_or_username
- **get_user_videos** — user_id_or_username`, `page`, `limit
- **search_user_videos** — user_id_or_username`, `keyword`, `page`, `limit
- **get_video_detail** — bvid`, `fetch_subtitles` (default: `false`), `subtitle_mode` (`smart`/`full`/`minimal`), `subtitle_lang` (default: `auto`), `subtitle_max_chars
- **get_user_dynamics** — user_id_or_username`, `cursor`, `limit`, `dynamic_type
- **get_user_articles** — user_id_or_username`, `page`, `limit
- **get_article_content** — article_id
- **get_user_followings** — user_id_or_username`, `page`, `limit
- **get_content_comments** — content_type`, `content_id`, `cursor`, `limit`, `sort
- **get_content_comment_replies** — content_type`, `content_id`, `root_rpid`, `page`, `limit

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "222wcnm-bilistalkermcp": {
    "command": "uvx",
    "args": ["bili-stalker-mcp"]
  }
}
```

## Documentation & README

# BiliStalkerMCP

[![Python](https://img.shields.io/badge/Python-3.12+-blue?logo=python)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-orange)](https://github.com/jlowin/fastmcp)
[![PyPI version](https://badge.fury.io/py/bili-stalker-mcp.svg)](https://pypi.org/project/bili-stalker-mcp/)
[![PyPI Total Downloads](https://static.pepy.tech/badge/bili-stalker-mcp)](https://pepy.tech/project/bili-stalker-mcp)

## Bilibili MCP Server for Specific User Analysis

BiliStalkerMCP is a Bilibili MCP server and command-line tool built on [Model Context Protocol (MCP)](https://modelcontextprotocol.io), 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 | [中文说明](https://github.com/222wcnm/BiliStalkerMCP/blob/HEAD/README_zh.md)**

## 🚀 Quick Start

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

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

```text
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

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

#### 2. Run from cloned source

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

Then replace `/path/to/BiliStalkerMCP` below with your actual absolute path:
```json
{
  "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:

```powershell
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:

```powershell
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:

```powershell
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.

```json
{
  "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:

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

For a PyPI-only invocation without cloning this repository:

```powershell
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:

```powershell
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_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`)

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

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.

## 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

```bash
# 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.

```powershell
# 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.

```bash
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.*