BiliStalkerMCP

Servidor MCP de Bilibili para Análisis de Usuarios Específicos

BiliStalkerMCP es un servidor MCP de Bilibili construido sobre el Model Context Protocol (MCP), diseñado para agentes de IA que necesitan analizar un usuario o creador específico de Bilibili.

Está optimizado para flujos de trabajo que comienzan con un uid o nombre de usuario objetivo, para luego recuperar el perfil, videos, dinámicas, artículos, subtítulos y seguimientos de ese usuario mediante herramientas estructuradas.

Si estás buscando un servidor MCP de Bilibili, un servidor de Bilibili para el Model Context Protocol, o un servidor MCP para rastrear y analizar un usuario específico de Bilibili, este repositorio está diseñado para ese caso de uso.

English | 中文说明

Instalación

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

Configuración (Claude Desktop, Recomendado)

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

Prefiere uv run --directory ... para actualizaciones locales más rápidas cuando la propagación de la versión en PyPI se retrase. Aún puedes usar uvx bili-stalker-mcp para un uso rápido y puntual.

Autenticación: Proporciona SESSDATA directamente, o colócalo en BILI_COOKIE_FILE. Obtenlo desde las Herramientas de Desarrollo del Navegador (F12) > Aplicación > Cookies > .bilibili.com.

Variables de Entorno

Actualización Segura de Cookies (Opcional)

La actualización automática está deshabilitada por defecto. Actívala solo cuando el archivo de cookies y el archivo de token de actualización existan, sean legibles y escribibles como archivos regulares. El archivo de cookies puede contener solo valores de cookies ordinarios (SESSDATA, bili_jct, buvid3, buvid4 y DedeUserID); el token de actualización pertenece solo a su propio archivo.

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

Cuando la actualización está habilitada, no establezcas SESSDATA, BILI_JCT ni DEDEUSERID en el entorno: esos valores rotativos deben provenir del archivo de cookies para que un reinicio no pueda recargar credenciales obsoletas. BUVID3 y BUVID4 aún pueden proporcionarse a través del entorno. Las comprobaciones de actualización tienen limitación de velocidad, y las llamadas MCP concurrentes o los procesos del servidor que comparten estos archivos utilizan un bloqueo de actualización. La confirmación pendiente se recupera antes de otra actualización. El archivo auxiliar .bili-cookie-refresh.lock puede permanecer en el disco entre ejecuciones.

Para una configuración inicial más rápida, copia el valor completo del encabezado Cookie de una solicitud del navegador a Bilibili y ac_time_value del Almacenamiento Local, luego ejecuta:

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

Para una invocación solo desde PyPI sin clonar este repositorio:

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

El script oculta ambos valores pegados, rechaza directorios dentro del repositorio y archivos de credenciales existentes, e imprime solo un bloque env de MCP no secreto. No pegues un comando cURL completo: pega solo el valor después de su encabezado cookie:.

Verificación Local

Todos los comandos de verificación utilizan simulaciones y no requieren credenciales de 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

Related MCP server: MediaCrawler MCP Server

Herramientas Disponibles

Al comenzar con un nombre de usuario, llama a search_users una vez y reutiliza el UID numérico devuelto para las herramientas posteriores. La resolución implícita de nombre de usuario acepta solo coincidencias exactas; no selecciona silenciosamente el primer resultado de búsqueda similar.

Las pictures de los comentarios contienen las URL de las imágenes originales. Los comentarios largos regulares conservan el texto completo devuelto por Bilibili. Los comentarios de tipo nota pueden contener solo una vista previa; usa el note.cvid devuelto con get_article_content para recuperar la nota completa. Para comentarios de video, pasa content_type="video" y un BVID, número AV o URL de video como content_id. Usa el rpid de un comentario principal como root_rpid al recuperar su hilo de respuestas completo.

Filtrado de Dinámicas (dynamic_type)

• ALL (predeterminado): Texto, Dibujo y Reenvíos.

• ALL_RAW: Sin filtrar (incluye Videos y Artículos).

• VIDEO, ARTICLE, DRAW, TEXT: Filtrado por categoría específica.

• REVIEW: Solo tarjetas de calificación de cinco ranuras reconocidas. Cada resultado expone review.rating (estrellas llenas, 0-5), review.title, review.text, URL de portada y salto, además de la descripción de la puntuación de origen cuando esté disponible. Este filtro no clasifica de forma independiente si el título calificado es un anime.

Cada elemento de dinámica incluye una lista images. Cada imagen contiene url, width y height; las URL no válidas se omiten y las dimensiones no disponibles son null. image_count siempre es igual al número de imágenes devueltas. Los reenvíos exponen los mismos campos bajo origin.images y origin.image_count. Las dinámicas sin imágenes devuelven una lista images vacía.

Paginación: Las respuestas incluyen next_cursor. Pasa esto en solicitudes posteriores para un desplazamiento continuo.

Modos de Subtítulos (get_video_detail)

• smart (predeterminado cuando fetch_subtitles=true): obtiene metadatos de todas las páginas, descarga solo el texto de la pista de subtítulos mejor coincidente.

• full: descarga el texto de todas las pistas de subtítulos (mayor costo).

• minimal: omite la obtención de metadatos de subtítulos y texto de subtítulos.

subtitle_lang puede forzar un idioma (por ejemplo, en-US); auto utiliza la prioridad de respaldo incorporada.
subtitle_max_chars limita el tamaño del texto de subtítulos devuelto para evitar la explosión de tokens.

El texto de los subtítulos se devuelve una vez a través de full_text; tracks solo transportan metadatos (text siempre está vacío). En el modo full con múltiples pistas, cada segmento en full_text tiene el prefijo de una etiqueta [idioma · parte].

Habilidad Empaquetada

El repositorio incluye una habilidad de agente de IA lista para usar en skills/bili-content-analysis/:

skills/bili-content-analysis/
├── SKILL.md                        # Workflow & output contract
└── references/
    └── analysis-style.md           # Detailed writing style rules

Qué Hace

Guía a agentes de IA compatibles (Gemini, Claude, etc.) a través de un flujo de trabajo estructurado de 6 pasos para un análisis profundo de contenido de Bilibili:

1. Clarificar objetivo y alcance (uid / bvid / keyword).

2. Recopilar evidencia — listas ligeras primero, detalles exhaustivos solo para elementos de alto valor.

3. Reconstruir estructura de la fuente antes de interpretar (cronología, capítulos, ponentes).

4. Analizar — hechos, cadena lógica, suposiciones, temas y cambios.

5. Conservar anclajes — uid, bvid, article_id, marcas de tiempo, fragmentos clave de la fuente.

6. Gestionar fallos — indicar bloqueadores explícitamente, detener especulación.

Uso

Copie la carpeta bili-content-analysis en el directorio de habilidades de su proyecto:

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

El agente activará automáticamente la habilidad cuando las solicitudes del usuario impliquen seguimiento de creadores de Bilibili, interpretación de transcripciones, reconstrucción de cronologías o análisis de contenido.

Desarrollo

# 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

Lanzamiento (Mantenedores)

Credenciales: El script de publicación utiliza UV_PUBLISH_TOKEN cuando está configurado; de lo contrario, lee el token [pypi] o [testpypi] correspondiente de $HOME\.pypirc. Twine se invoca transitoriamente a través de uvx solo para validación de metadatos del paquete y no es una dependencia del proyecto.

# 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

Se ejecuta a través del transporte stdio. No hay puertos expuestos.

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

Solución de problemas

• 412 Precondition Failed: Se activó el sistema anti-crawling de Bilibili. Refresque SESSDATA o proporcione BUVID3.

• IPs en la nube: Altamente susceptibles al bloqueo; se recomienda ejecución local.

Licencia

MIT

Descargo de responsabilidad: Solo para investigación y aprendizaje personal. Queda prohibido el perfilado masivo, el acoso o la vigilancia comercial.

Este proyecto se construye y mantiene con la ayuda de IA.