bangumi-mcp

Roxy Plugin API v2 plugin that uses Bangumi's official API to paginate through collection lists, query the exact progress of a single entry, set "watching/watched", update animation watch progress episode by episode via the chapter endpoint, and proactively remind users of new episodes of anime they are watching based on AniList's scheduled airing time.

Security Boundaries

• Only connects to https://api.bgm.tv and https://graphql.anilist.co, using a compliant User-Agent per official requirements.

• Bangumi Access Token and AniList Access Token are read only from config.local.toml in Roxy plugin-data; never written to repositories, logs, or tool results.

• All remote writes first generate a preview containing the work name and target status/episode count; confirmation is recorded for one-time use and expires after 10 minutes.

• When a full collection query or cumulative reads reach 100 entries, the read-only query scope and estimated request count are displayed first, waiting for word-for-word confirmation after the current round.

• Animation progress uses PATCH /v0/users/-/collections/{subject_id}/episodes with explicit episode IDs, not the item-level ep_status to modify anime episode counts.

Related MCP server: Anitabi MCP Server

Installation

Roxy only installs committed Git snapshots. Execute from the Roxy repository:

.venv/bin/python main.py plugin-install \
  --source https://github.com/roxy-plugins/bangumi-mcp.git \
  --marketplace github

The installation output indicates the data directory, which by default is:

<workspace>/plugin-data/bangumi-github/

After logging into Bangumi, go to the Bangumi Access Token page to generate a personal token. This token is the account's API access credential, not the Bangumi password.

Create a config.local.toml in that directory with permissions 0600:

access_token = "<在此填写 Bangumi Access Token>"
user_agent = "roxy-plugins/bangumi-mcp/0.5.0 (https://github.com/roxy-plugins/bangumi-mcp)"

[anime_push]
enabled = true
notify_before_minutes = 0
display_timezone = "Asia/Shanghai"
anilist_token = "<在此填写 AniList Access Token>"

# 只有自动匹配失败时才需要配置；左侧是 Bangumi subject ID。
[anime_push.media_id_overrides]
"501963" = 123456

If you have an older version installed and explicitly set user_agent in your local configuration, change it to the new identifier above after updating the plugin. Do not put tokens in command-line arguments or chat messages. After configuration, check:

.venv/bin/python main.py plugin-doctor bangumi@github

A running Roxy watches for configuration changes and publishes a new committed generation; new sessions load the bangumi Skill and MCP tools.

Airing Reminders

• Reminders are based on AniList nextAiringEpisode.airingAt, with precision normalized to the minute; it indicates scheduled airing, not the availability of streaming, subtitles, or raw sources.

• notify_before_minutes=0 starts waiting from the scheduled airing time; can be set to an integer from 0 to 1440 to remind in advance.

• At the reminder moment, Roxy reads the event on the next proactive tick. Gate, Judge, session busyness, or channel state may delay the message by several minutes.

• The plugin only processes anime marked as "watching" on Bangumi, and before generating a reminder, it confirms via the per-episode endpoint that the episode has not yet been marked as "watched".

• AniList and Bangumi do not share a common stable ID. Automatic matching only accepts a single strict candidate; on failure, you can explicitly specify an AniList media ID in the media_id_overrides field of the private configuration.

• Enabling anime_push requires configuring an AniList Access Token; it can only be written to the above plugin-data private file, not placed in command lines, conversations, or repositories.

• Cache, pending events, and ACKs are stored in anime_updates.db in the same plugin-data directory. Disabling anime_push.enabled does not delete this database.

Design Documents

• User Collection List Design

• Collection Query Intent and Display Boundaries

• Full Collection and Large Query Confirmation Boundaries

• Update Push Reminder Design

Development Verification

python -m pip install -r mcp/requirements.txt -r requirements-dev.txt
pytest
PYTHONPATH=/path/to/plugin-contracts \
  python -m akashic_plugin_contracts check plugin.py

All unit tests use fake HTTP sessions, do not access real Bangumi accounts, and do not require Access Token.