222wcnm-bilistalkermcp

BiliStalkerMCP

特定ユーザー分析向け Bilibili MCP サーバー

BiliStalkerMCP は、Model Context Protocol (MCP) を基盤として構築された Bilibili MCP サーバーおよびコマンドラインツールです。特定の Bilibili ユーザーやクリエイターを分析する必要がある AI エージェント向けに設計されています。

対象の uid またはユーザー名を起点に、そのユーザーのプロフィール、動画、動態、記事、字幕、フォロー中のユーザーを構造化されたツールで取得するワークフローに最適化されています。

Bilibili MCP サーバー、Bilibili Model Context Protocol サーバー、または特定の Bilibili ユーザーを追跡・分析するための MCP サーバーをお探しの場合、このリポジトリはその用途向けに設計されています。

英語 | 中国語の説明

🚀 クイックスタート

🤖 方法 1：AI エージェントに設定を任せる（推奨）

以下をコピーして、Claude Code、Codex、またはその他の AI エージェントに送信してください。

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

---

🛠️ 方法 2：手動で設定する（MCP クライアント）

設定パスと構文は、クライアントによって異なる場合があります。

1. PyPI リリースを直接実行する

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

2. クローンしたソースから実行する

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

以下の /path/to/BiliStalkerMCP を、実際の絶対パスに置き換えてください。

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

PyPI リリースの反映が遅れている場合は、ローカルでの更新を速くするために uv run --directory ... を推奨します。 使い捨ての用途には、引き続き uvx bili-stalker-mcp を使用できます。

認証：SESSDATA を直接指定するか、BILI_COOKIE_FILE に保存してください。ブラウザーの開発者ツール（F12）＞ Application ＞ Cookies ＞ .bilibili.com から取得できます。

方法 3：コマンドラインからのクエリ

このチェックアウトから CLI を使用すると、MCP クライアントを設定したり、常時稼働するサーバーを起動したりせずに、12 個のツールのいずれかにクエリできます。

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 は名前と説明を一覧表示し、tools TOOL は必須引数、デフォルト値、制限を含む完全な MCP スキーマを返します。call TOOL は MCP ツールと同じ名前および JSON 引数を受け付けます。スキーマで文字列として宣言されている ID は、数値の UID や長い記事 ID／動的 ID も含め、引用符で囲んだままにする必要があります。 doctor は、認証情報の取得元、更新設定、プロキシ設定、依存関係のバージョンに関する診断情報を JSON で出力します。デフォルトでは、ネットワークを使用せず、認証情報ファイルを変更せず、認証情報の値も出力しません。doctor --network を指定すると TCP 接続チェックが追加されますが、ログインや API 応答は検証しません。

引数が大きい場合や、シェルでの引用符の問題を避ける場合は、UTF-8 の JSON ファイルを読み込むか、JSON オブジェクトを標準入力経由で渡してください。

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 -

以下の環境変数を呼び出し元のシェルで設定してください。たとえば、PowerShell では $env:BILI_COOKIE_FILE = 'D:\BiliStalkerSecrets\bili-cookie.txt' のように設定します。MCP クライアントの env 設定は、別のターミナルには自動的に引き継がれません。CLI は MCP と同じ認証情報、更新、プロキシ、レート制限の動作を使用します。ヘルプ、バージョン、ツールの検出にはログイン認証情報は必要ありません。

チェックアウトに .env ファイルがすでにある場合は、コマンドで明示的に読み込んでください。CLI も通常の uv run も、自動的には読み込みません。

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

クエリが成功すると、UTF-8 の JSON 値が 1 つ標準出力に書き込まれます。ログとエラーは標準エラー出力に送られます。結果を保存するには、標準出力をリダイレクトしてください。終了コードは、成功が 0、クエリ／設定の失敗（doctor の異常レポートを含む）が 1、無効なコマンドまたは引数が 2、中断が 130 です。クエリおよび引数の失敗時は、標準エラー出力の末尾に JSON の error オブジェクトが出力されます。リスク制御エラーでは code と retry_after が保持されます。スナップショットはセクションが不完全な状態でも成功する場合があります。解釈する前に errors フィールドを確認してください。

uv run python -m bili_stalker_mcp ... でも同じ引数を使用できます。パッケージをインストール済みの場合は、bili-stalker-mcp ... を直接使用してください。サブコマンドを指定せずに実行すると、MCP stdio サーバーが起動します。明示する場合は bili-stalker-mcp serve を使用してください。

環境変数

キー	必須	説明
SESSDATA	条件付き	Bilibili のセッショントークンです。BILI_COOKIE_FILE から取得できない場合に必要です。
BILI_JCT	いいえ	CSRF 保護トークンです。
BUVID3	いいえ	ハードウェアフィンガープリントです（レート制限のリスクを軽減します）。
BILI_COOKIE_FILE	いいえ	プレーンな Cookie ファイルへのパスです。
BILI_REFRESH_TOKEN_FILE	いいえ	個別の更新トークンファイルへのパスです。トークンを環境変数で設定しないでください。
BILI_ENABLE_COOKIE_REFRESH	いいえ	true にすると、安全な自動更新が有効になります。デフォルト：false。
BILI_COOKIE_REFRESH_CHECK_INTERVAL_SECONDS	いいえ	更新チェックの間隔です。デフォルト：21600、最小値：60。
BILI_PROXY	いいえ	すべての上流リクエスト（bilibili_api と組み込みの HTTP クライアント）をこのプロキシ経由にします。システムプロキシが自動的に認識されない場合や、Bilibili ホストの DNS 解決が不安定な場合に推奨されます。起動時にプロキシへ接続できない場合、サーバーは直接接続に切り替え、警告をログに記録します。
BILI_REQUEST_JITTER_MODE	いいえ	上流リクエストのジッター動作です。adaptive（デフォルト。ログインが設定されていない場合、または直近に 412／429／403 が発生した場合のみスリープします）、always、never を指定できます。
BILI_REQUEST_JITTER_MIN_MS / BILI_REQUEST_JITTER_MAX_MS	いいえ	ジッターによるスリープ時間の範囲です。デフォルト：200～1200。
BILI_REQUEST_JITTER_BUDGET_MS	いいえ	1 回のツール呼び出しで許可されるジッターによるスリープ時間の合計です。デフォルト：500。
BILI_RISK_PRESSURE_WINDOW_SECONDS	いいえ	412／429／403 の発生後、適応型ジッターを有効に保つ時間です。デフォルト：300。
BILI_LOG_LEVEL	いいえ	DEBUG、INFO（デフォルト）、WARNING を指定できます。
BILI_TIMEZONE	いいえ	フォーマット済みタイムスタンプの出力タイムゾーンです（デフォルト：Asia/Shanghai）。

オプションの安全な Cookie リフレッシュ

自動リフレッシュはデフォルトで無効です。Cookie ファイルとリフレッシュトークンファイルが存在し、読み取り可能かつ書き込み可能な通常ファイルである場合にのみ有効にしてください。Cookie ファイルには通常の Cookie 値（SESSDATA、bili_jct、buvid3、buvid4、DedeUserID）のみを含めることができます。リフレッシュトークンは専用のファイルにのみ保存してください。

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

リフレッシュを有効にする場合、環境変数にSESSDATA、BILI_JCT、DEDEUSERIDを設定しないでください。これらのローテーションする値は Cookie ファイルから取得する必要があります。そうすることで、再起動時に古い認証情報が再読み込みされるのを防げます。BUVID3とBUVID4は引き続き環境変数で指定できます。リフレッシュのチェックにはレート制限が適用されます。また、これらのファイルを共有する複数の MCP 呼び出しやサーバープロセスは、1つのリフレッシュロックを使用します。次のリフレッシュの前に、保留中の確認が復元されます。.bili-cookie-refresh.lockサイドカーファイルは、実行と実行の間もディスク上に残ることがあります。

初期設定を手早く行うには、Bilibili のブラウザーリクエストから Cookie ヘッダーの値全体をコピーし、ローカルストレージからac_time_valueをコピーして、次を実行してください。

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

このリポジトリをクローンせずに PyPI のみで実行する場合：

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

このスクリプトは、貼り付けた2つの値を非表示にし、リポジトリ内のディレクトリと既存の認証情報ファイルを拒否して、秘密情報を含まない MCP のenvブロックのみを表示します。cURL コマンド全体を貼り付けないでください。cookie:ヘッダーの後に続く値のみを貼り付けてください。

ローカルでの検証

すべての検証コマンドはモックを使用し、Bilibili の認証情報は不要です。

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

利用可能なツール

ツール	機能	パラメーター
search_users	数値 UID を含む軽量なユーザー候補	keyword、limit
get_user_snapshot	1回の呼び出しで概要を取得：プロフィールと最近の動画／ダイナミック／記事を並行して取得	user_id_or_username、video_limit、dynamic_limit、article_limit（0の場合は該当セクションをスキップ）
get_user_info	詳細なプロフィール：レベル、公式タイトル、VIP、ライブ配信ルーム、アカウント停止状態、フォロー数／フォロワー数、動画再生数／記事閲覧数／いいね数の合計（bili_jctが必要）	user_id_or_username
get_user_videos	軽量な動画一覧	user_id_or_username、page、limit
search_user_videos	1人のユーザーの動画一覧をキーワード検索	user_id_or_username、keyword、page、limit
get_video_detail	動画の詳細情報と、オプションで字幕	bvid、fetch_subtitles（デフォルト：false）、subtitle_scope（single／all、デフォルト：single）、subtitle_page、subtitle_cid、subtitle_mode（smart／full／minimal）、subtitle_lang（デフォルト：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	記事の Markdown 全文	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

ユーザー名から検索を始める場合は、search_usersを1回呼び出し、以降のツールでは返された数値 UID を再利用してください。暗黙的なユーザー名解決では完全一致のみが許可され、類似する検索結果の先頭が自動的に選択されることはありません。

コメントのpicturesには元画像の URL が含まれます。通常の長いコメントには、Bilibili から返された全文が保持されます。ノート形式のコメントにはプレビューのみが含まれる場合があります。ノート全文を取得するには、返されたnote.cvidをget_article_contentで使用してください。動画コメントの場合は、content_type="video"を指定し、BVID、AV 番号、または動画 URL をcontent_idとして渡してください。トップレベルのコメントスレッド全体を取得するには、そのコメントのrpidをroot_rpidとして使用してください。

動的コンテンツのフィルタリング（dynamic_type）

• ALL（デフォルト）：テキスト、画像、リポスト、動画の動的コンテンツです。
• ALL_RAW：フィルタリングなし（記事と不明な種類も含まれます）。
• VIDEO、ARTICLE、DRAW、TEXT：特定のカテゴリでフィルタリングします。
• REVIEW：認識された5つ星評価カードのみが対象です。各結果には review.rating（塗りつぶされた星の数、0～5）、review.title、review.text、カバー画像と 遷移先のURL、および利用可能な場合はソースの評価説明が含まれます。このフィルターでは、 評価対象のタイトルがアニメかどうかは個別に判定しません。

各動的コンテンツ項目にはimagesリストが含まれます。各画像にはurl、width、 heightが含まれます。無効なURLは除外され、取得できない寸法はnullになります。 image_countは常に返された画像の数と一致します。リポストでは同じ フィールドがorigin.imagesとorigin.image_countに含まれます。画像を含まない動的コンテンツでは、 imagesリストは空になります。

ページネーション：レスポンスにはnext_cursorが含まれます。スムーズにスクロールするには、以降のリクエストにこれを渡してください。

字幕モード（get_video_detail）

ページ範囲は言語／トラックモードとは独立しています。デフォルトのsubtitle_scope="single" では、smartとfullのどちらでもP1のみを問い合わせます。p=2を含む完全なURLを指定するとP2が選択されます。 または、subtitle_page=2か、この動画に属するsubtitle_cidを渡してください。 ページとCIDは正の整数である必要があり、2つの明示的なセレクターは同時に指定できません。 URLと明示的な選択の競合、存在しないページ、別の動画のCIDを指定した場合は、別のページにフォールバックせずに invalid_subtitle_selectionを返します。

すべてのページを対象にするには、BVIDまたはpを含まないURLとともにsubtitle_scope="all"を明示的に設定してください。 ページ／CIDセレクターやURLのpとは併用できません。全範囲では各ページの字幕メタデータを引き続きすべて走査しますが、 単一範囲では選択したページのみを問い合わせます。 デフォルトの動作が変更されています。以前の全ページ走査に依存していた呼び出し側は、subtitle_scope="all"を追加する必要があります。

• smart（fetch_subtitles=trueの場合のデフォルト）：選択した範囲内で最も適合するトラックを1つダウンロードします。
• full：選択した範囲内のすべての言語トラックをダウンロードします（コストが高くなります）。
• minimal：字幕メタデータと字幕テキストの取得をスキップします。

smartモードでは、subtitle_langで言語を指定できます（例：en-US）。 autoでは組み込みの優先順位に基づいてフォールバックします。 subtitle_max_charsは、トークンが過剰に増えるのを防ぐため、返される字幕テキストのサイズに上限を設定します。

字幕テキストはfull_text経由で一度だけ返されます。tracksにはメタデータのみが含まれます （textは常に空です）。複数のトラックがあるfullモードでは、full_text内の各セグメントの先頭に [language · part]ラベルが付きます。

動画の詳細には、owner: {mid, name, face}（またはnull）、duration（全パートの上流合計秒数）、pic、tname、 videos、およびctime（Unix秒）が含まれます。メタデータがない場合はnullになります。pages[]には各パートの cid/page/part/durationが保持され、パートの長さは秒単位です。midとuidはいずれもBilibili ユーザーを識別します。空のtags配列は、詳細情報のソースにタグが含まれていなかったことを示す場合もあります。

selected_languageはsmartモードでのみ設定されます。fullモードではnullを返し、言語はtracks[].lanに一覧表示されます。 truncated=trueは、文字数上限によって字幕テキストが切り詰められた、または除外されたことを示します。ダウンロードに失敗したトラックも tracksに残る場合があります。errorsとfull_textを確認してください。字幕テキストにタイムコードはありません。

subtitles.scopeにはmode、target_page、total_pages、returned_pages、および summaryが含まれ、選択した範囲と返されたテキストに実際に含まれるページを区別するとともに、返されたテキストがないページ数を示します。 returned_pagesは、そのページから少なくとも1文字のテキストが返されたことを意味しますが、完全な内容が返されたとは限らないため、 errorsとtruncatedを確認してください。動画のpages[]には常にページの完全な一覧が保持されます。字幕が無効の場合、scopeは nullとなり、セレクターは適用されません。minimalでは選択した範囲を検証しますが、テキストを含むページは返さず、 字幕APIも呼び出しません。

同梱スキル

このリポジトリには、すぐに使えるAIエージェントスキルが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

機能

互換性のある AI エージェント（Gemini、Claude など）を、MCP ツールまたは CLI を使った Bilibili コンテンツの詳細分析のための、次の 6 ステップのワークフローに沿ってガイドします。

1. 対象と範囲の明確化 — 対象と範囲（uid / bvid / キーワード）を確認します。
2. 証拠の収集 — まずは軽量なリストを取得し、重要度の高い項目に限って詳細を取得します。
3. ソース構造の再構成 — 解釈の前に、タイムライン、章、話者を整理します。
4. 分析 — 事実、論理の流れ、前提、テーマ、変化を分析します。
5. 根拠の保持 — uid、bvid、article_id、タイムスタンプ、重要なソースの抜粋を記録します。
6. 失敗への対応 — 障害要因を明示し、推測を中止します。

使用方法

bili-content-analysis フォルダーをプロジェクトのスキルディレクトリにコピーします。

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

ユーザーのリクエストが Bilibili クリエイターの追跡、文字起こしの解釈、タイムラインの再構成、コンテンツ分析に関する場合、エージェントはこのスキルを自動的に有効化します。

開発

# 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

リリース（メンテナー向け）

認証情報：リリーススクリプトは、UV_PUBLISH_TOKEN が設定されている場合はこれを使用し、設定されていない場合は $HOME\.pypirc から対応する [pypi] または [testpypi] トークンを読み込みます。 Twine はパッケージメタデータの検証に限り、uvx を通じて一時的に呼び出されます。プロジェクトの依存関係には含まれません。

# 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

stdio トランスポートで実行します。ポートは公開しません。

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

トラブルシューティング

• 412 Precondition Failed：Bilibili のアンチクローリングシステムが作動しました。SESSDATA を更新するか、BUVID3 を指定してください。
• クラウド IP：ブロックされやすいため、ローカルでの実行を推奨します。
• 上流への呼び出しで約 20 秒の停止や DNS タイムアウトが発生する場合：BILI_PROXY を設定してください。bilibili_api の curl_cffi クライアントは、明示的にプロキシを設定しない限り、システムおよび環境変数のプロキシ設定を無視します。

上流依存関係に関する注意

bilibili-api-python は ==17.4.2 に固定されています。Bilibili からの法的通知を受けて、上流リポジトリは恒久的に閉鎖されたため、このプロジェクトから今後メンテナンスや修正が提供されることはありません。また、このパッケージは GPL-3.0-or-later ライセンスで提供されているため、ソースコードをこの MIT ライセンスのリポジトリに 同梱したり、フォークしたりすることはできません。

対応策として、残る SDK 依存のエンドポイント（ユーザー情報、動画リスト、動画詳細の字幕、ダイナミック、記事）を、このプロジェクト独自の生 HTTP スタック（SharedRawHttpClient）へ段階的に移行します。このスタックはすでに SDK に依存せず、コメント、フォロー一覧、関係統計、字幕なしの動画詳細を提供しています。インストール時に未知の将来バージョンが選ばれないよう、バージョン固定は厳密に維持してください。

ライセンス

MIT

免責事項：個人的な調査および学習のみを目的としています。大規模なプロファイリング、嫌がらせ、商業的な監視は禁止されています。

---

このプロジェクトは AI の支援を受けて開発・メンテナンスされています。