Bangumi MCP 服务

Bangumi MCP

中文版本

A Model Context Protocol server for the Bangumi API

Bangumi MCP gives MCP clients access to Bangumi (bgm.tv): anime, manga, books, music, games, characters, staff, indices and personal collections.

The project is built on the MCP Python SDK 2.3 (protocol revision 2026-07-28) and tracks the 2026-07-24 revision of the Bangumi OpenAPI document bundled at bangumi_mcp/dist.json.

Highlights

• 11 intent-based tools instead of one tool per REST endpoint. Each tool covers a whole workflow, so the catalogue stays small without losing access to any of the 56 operations exposed by the 47 Bangumi API paths.
• Generated, validated schemas: inputs come from Python type hints and outputs from Pydantic models. Clients receive outputSchema and structuredContent and can validate results themselves.
• MCP 2.x features: tool annotations, cache hints, resources, prompts, progress reporting, Streamable HTTP (stateful or stateless) and legacy SSE.
• Bangumi-aware: correct filter.tag search payloads, batched episode updates, token-scope hints, retries for rate limits and public reads that keep working when the configured token has expired.

Quick start

git clone https://github.com/etherwindy/Bangumi-MCP.git
cd Bangumi-MCP
uv sync
uv run bangumi-mcp --help

Set a Bangumi access token (optional for public reads, required for /v0/me and every write):

# .env
BANGUMI_API_TOKEN=your_api_token_here

Create tokens at https://next.bgm.tv/demo/access-token. The current Bangumi spec marks mutating endpoints with OAuth scopes:

A 403 answer includes a hint telling you which scope is missing.

Tools

All tools are annotated with readOnlyHint, destructiveHint, idempotentHint and openWorldHint.

The API has no endpoint for deleting an index. Indices created with bangumi_manage_index(action="create") must be removed on bgm.tv.

Known upstream limitation: Bangumi's API advertises DELETE /v0/characters/{id}/collect and DELETE /v0/persons/{id}/collect but the server does not implement them (bangumi/api#234). bangumi_update_collection(action="unset") therefore returns a clear error for characters and persons; uncollect them on https://bgm.tv for now.

Image URLs are part of the subject/character/person/user payloads, so there is no separate image tool. bangumi_get_subject(subject_id=..., include=[...]) replaces the old get_subject_info / get_subject_persons / get_subject_characters / get_subject_relations family.

Migrating from 0.1.x

The 55 endpoint tools were consolidated into the 11 tools above. No functionality was dropped.

MCP features in use

• SDK 2.x / MCPServer — the high-level server class (formerly FastMCP). Handlers are typed functions; schemas are generated from type hints, not maintained by hand.
• Protocol 2026-07-28 — no handshake and no session on modern connections, tools/list cache hints, resources/read cache hints and per-request routing headers. The same process still serves 2025-era clients (including the legacy HTTP+SSE transport).
• Structured output — each tool declares an outputSchema; results are returned as both text and structuredContent. The client validates structured content, which is why nullable Bangumi fields are modelled as nullable and null values are dropped from payloads.
• Annotations and titles — every tool carries human-readable titles and MCP hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).
• Resources — bangumi://calendar plus bangumi://subject/{id}, bangumi://character/{id}, bangumi://person/{id} and bangumi://user/{username} templates let clients attach Bangumi data without tool calls.
• Prompts — bangumi_recommend, bangumi_subject_deep_dive and bangumi_backlog_review provide ready-made workflows.
• Progress — multi-fetch tools (bangumi_get_subject, bangumi_get_entity) report progress while loading related sections.
• Transport control — --stateless for session-less Streamable HTTP and --json-response for clients that prefer JSON over SSE streams.

Configuration

.env files in the working directory are loaded automatically. If a token is present but expired, public reads automatically retry anonymously; only authenticated calls fail, with a hint pointing at the token page.

Usage

STDIO

{
  "mcpServers": {
    "Bangumi-MCP": {
      "command": "uv",
      "args": ["--directory", "/path/to/Bangumi-MCP", "run", "bangumi-mcp"],
      "env": {
        "BANGUMI_API_TOKEN": "your_token_here"
      }
    }
  }
}

Streamable HTTP

uv run bangumi-mcp --mode=streamable_http --host localhost --port 18080

{
  "mcpServers": {
    "Bangumi-MCP": {
      "type": "streamableHttp",
      "url": "http://localhost:18080/mcp"
    }
  }
}

Add --stateless to avoid server-side sessions entirely, or --json-response to receive plain JSON responses.

SSE (legacy clients)

uv run bangumi-mcp --mode=sse --host localhost --port 18080

{
  "mcpServers": {
    "Bangumi-MCP": {
      "type": "sse",
      "url": "http://localhost:18080/sse"
    }
  }
}

SSE exists for clients that still use the 2025-era handshake. New clients should use Streamable HTTP.

Development

uv sync
uv run pytest
uv run python scripts/update_openapi.py --check   # is the bundled schema stale?
uv run python scripts/update_openapi.py           # refresh it

Layout:

bangumi_mcp/
  __main__.py        CLI (stdio / sse / streamable_http)
  mcp_server.py      MCPServer factory, transports, cache hints
  bangumi_client.py  httpx client, retries, error mapping
  models.py          Pydantic models used for output schemas
  resources.py       MCP resources
  prompts.py         MCP prompts
  tools/             one module per tool group
scripts/update_openapi.py
tests/

When refreshing the OpenAPI document, review the diff and update bangumi_mcp/models.py, bangumi_client.py and the tool descriptions if an endpoint or payload changed.

Acknowledgements

Originally built with the assistance of Qwen3-Coder and Claude Sonnet 4.

License

MIT — see LICENSE.