Bangumi MCP: A Lightweight HTTP MCP Service

项目已开源在 Tokisaki-Galaxy/bangumimcp-ts，欢迎点 star。

第三方 MCP 服务器不建议直接用于敏感账号。涉及收藏、评论、个人信息时，更适合自建。

如果你想把 Bangumi 接到 Claude、Cursor、Copilot 这类支持 MCP 的客户端里，真正麻烦的地方通常不是接入，而是工具太多，模型不好选。

这个项目做的事情很直接。它把 Bangumi API 封装成一个可部署在 Cloudflare Workers 上的 HTTP MCP 服务，再把原本分散的几十个接口收敛成更容易理解的 8 个入口。

为什么要做成 MCP

Bangumi 的能力很完整。条目、人物、角色、收藏、目录、章节、编辑历史，都有对应接口。

问题也很明显。对大模型来说，工具太多会带来两个负担。

1. 容易选错工具
2. 一次上下文里塞进太多说明

所以这里的思路不是把每个接口原样暴露，而是把常用动作聚合起来，让模型先理解“要做什么”，再去调用具体工具。

如何使用

在支持 MCP 的客户端里，直接添加服务器地址即可。

https://bgm.api.tski.uk/mcp

如果你需要写入收藏、修改进度、收藏人物或角色，再补充个人令牌。

https://next.bgm.tv/demo/access-token/create

部署方式

一键部署

Fork 后部署

Fork Tokisaki-Galaxy/bangumimcp-ts 到自己的账户，再在 Cloudflare 里连接 GitHub 仓库即可。

部署前提

• 一个 Cloudflare 账号
• 一个 GitHub 仓库连接

暴露的 8 个工具

这个 MCP 默认只暴露这 8 个入口。

• search
• get_subject
• get_user
• get_calendar
• update_collection
• get_person
• get_character
• manage_index（默认关闭）

search

一个入口搜索三类对象：条目、人物、角色。

它支持 scope 限定搜索范围，也支持分页和筛选参数。模型一般先搜索，再决定要不要展开详情。

get_subject

条目详情入口。它不只返回标题和简介。

还可以通过 include 展开这些内容：

• persons
• characters
• relations
• episodes

这样模型可以一次拿到主信息和关联信息，减少来回调用。

get_user

用户画像入口。

它会返回用户资料和收藏快照，适合看“这个人平时看什么、收藏什么、偏好什么”。

get_calendar

放送表入口。

如果你想查今天或本周有哪些番在播，这个工具最直接。

update_collection

这是唯一的写入口。

我把“收藏条目”“改进度”“收藏人物”“收藏角色”统一到一个入口里，再由 target_type 严格分流。

• target_type=subject 才能用 subject_status / progress / rating / comment
• target_type=person 或 target_type=character 只能用 favorite

这样可以避免模型把无关参数混着传。

get_person

人物详情入口。它会同时带出人物相关作品和角色信息。

get_character

角色详情入口。它会同时带出出演作品和声优相关信息。

manage_index

目录管理入口，但默认关闭。

只有显式开启环境变量后，它才会出现在工具列表里。

这次收敛工具的原因

核心不是删功能，而是降低认知成本。

对模型来说，工具越少越好选。对人来说，入口越聚合越容易记。

以前可能会拆成这些工具：

• get_subject_details
• get_subject_persons
• get_subject_characters
• get_subject_relations
• get_episodes

现在变成一个 get_subject，通过 include 就能拿到需要的展开数据。

这类设计对 MCP 很关键，因为 MCP 的目标不是给人写脚本，而是给模型调用。

这版做了哪些细节处理

部分失败不会炸全局

像 get_subject、get_user、get_person、get_character 这种聚合工具，内部会并行拉多个子接口。

如果其中某个子请求失败，不会直接打断整次调用，而是把那一段结果标成 _error。

这样模型还能继续使用其余可用信息。

写参数会严格校验

update_collection 不会再“尽量帮你猜”。

如果参数组合不合法，直接返回 invalid_argument。

这对模型很重要。静默忽略会让它误以为自己写成功了。

nsfw_filter 会正常透传

搜索角色时，如果用户没有 token，Bangumi 本身会忽略 NSFW 过滤条件，而不是报错。

所以这个 MCP 会把参数原样传下去，让后端按权限处理。

适合什么场景

• 用自然语言查 Bangumi 条目
• 让模型总结人物、角色和条目关系
• 快速查看收藏状态和放送表
• 用更少的工具让客户端更稳定地选工具

总结

这版 Bangumi MCP 的方向很明确。

少而稳的工具入口，配合清晰的语义说明。

它不是把 Bangumi API 全部摊开给模型，而是把常见操作聚合起来，让 MCP 更像一个可对话的 Bangumi 门面。

如果目标是让 AI 真正好用地访问 Bangumi，这种收敛过的工具设计，通常比接口全暴露更有效。

The project is open-sourced at Tokisaki-Galaxy/bangumimcp-ts. Feel free to star it.

Do not use third-party MCP servers for sensitive accounts. If you need to write collections or handle personal data, self-hosting is safer.

If you want to connect Bangumi to MCP-capable clients such as Claude, Cursor, or Copilot, the hard part is often not the connection itself. The real problem is too many tools, which makes it harder for the model to choose the right one.

This project takes a simple approach. It wraps the Bangumi API into an HTTP MCP service deployable on Cloudflare Workers, then reduces dozens of fine-grained endpoints into 8 tools that are easier for the model to understand.

Why I turned it into MCP

Bangumi is a very rich service. It has entries, people, characters, collections, indexes, episodes, and revision history. The API surface is broad and capable.

That also creates two problems for LLMs.

1. It is easy to pick the wrong tool
2. Too many tool descriptions can fill the context window

So the goal here is not to expose every endpoint as-is. The goal is to group common actions so the model can understand the intent first, then call a specific tool.

How to use it

Add the MCP server URL directly in your MCP client.

https://bgm.api.tski.uk/mcp

If you want to write collections, update progress, or favorite people and characters, you also need a personal access token.

https://next.bgm.tv/demo/access-token/create

Deployment

One-click deploy

Deploy by forking

Fork Tokisaki-Galaxy/bangumimcp-ts to your own account, then connect the repository in Cloudflare.

Requirements

• A Cloudflare account
• A GitHub repository connection

The 8 exposed tools

By default, this MCP exposes only these 8 entry points.

• search
• get_subject
• get_user
• get_calendar
• update_collection
• get_person
• get_character
• manage_index (disabled by default)

search

One tool for three object types: entries, people, and characters.

It supports scope to limit the search range, plus pagination and filter parameters. The usual flow is to search first, then expand details later if needed.

get_subject

This is the entry tool for subject details. It returns more than a title and summary.

It can also expand these sections through include:

• persons
• characters
• relations
• episodes

That means the model can fetch main data and related data in one call.

get_user

This is the user profile tool.

It returns user data and a collection snapshot, which is useful for understanding what a user usually watches, collects, or prefers.

get_calendar

This is the broadcast calendar tool.

If you want to check what is airing today or this week, this is the most direct entry point.

update_collection

This is the only write tool.

I intentionally grouped “collect an entry,” “update progress,” “favorite a person,” and “favorite a character” into one tool, then route them strictly by target_type.

• target_type=subject can use subject_status / progress / rating / comment
• target_type=person or target_type=character can only use favorite

This avoids mixing unrelated parameters.

get_person

This is the person detail tool. It also returns related works and character information.

get_character

This is the character detail tool. It also returns works and voice actor related information.

manage_index

This is the index management tool, but it is disabled by default.

It appears in the tool list only after the environment variable is enabled.

Why the tool set was reduced

The point is not to remove features. The point is to reduce cognitive cost.

For the model, fewer tools are easier to choose from. For people, fewer entry points are easier to remember.

Before this change, the service could have exposed tools like:

• get_subject_details
• get_subject_persons
• get_subject_characters
• get_subject_relations
• get_episodes

Now they are folded into a single get_subject, and include decides which expanded data to return.

That matters for MCP, because MCP is not mainly for writing scripts. It is for model calls.

A few implementation details

Partial failures do not break the whole call

Aggregated tools such as get_subject, get_user, get_person, and get_character fetch multiple sub-resources in parallel.

If one sub-request fails, the whole call does not fail. That section is returned as _error instead.

The model can still use the rest of the data.

Write parameters are validated strictly

update_collection no longer tries to guess your intent.

If the parameter combination is invalid, it returns invalid_argument.

That is important for LLMs. Silent fallback makes the model believe the write already succeeded.

nsfw_filter is passed through normally

When searching characters without a token, Bangumi itself ignores the NSFW filter instead of raising an error.

So this MCP passes the parameter through unchanged and lets the backend handle permissions.

Good use cases

• Query Bangumi entries with natural language
• Ask the model to summarize people, characters, and entry relationships
• Check collection status and the broadcast calendar quickly
• Keep client-side tool selection stable with fewer tools

Closing

The direction of this Bangumi MCP is very clear.

Small, stable tools with clear semantics.

It does not expose the whole Bangumi API to the model. It groups common actions into a more conversational Bangumi front door.

If the goal is to make AI access Bangumi in a practical way, this kind of reduced tool design is usually more effective than exposing every endpoint.