Bangumi MCP Server

April 22, 2026 · View on GitHub

English | 中文

English

A Model Context Protocol (MCP) server that provides programmatic access to the Bangumi TV API, enabling AI assistants like Claude to interact with comprehensive anime, manga, music, game, and real-world media data.

Features

  • 55 MCP Tools: Complete coverage of Bangumi API endpoints
  • 3 Workflow Prompts: Pre-built multi-step workflows for common tasks
  • 1 Resource: Full OpenAPI specification for API documentation
  • Modular Architecture: Clean, maintainable codebase following MCP best practices
  • Type-Safe: Full Python type hints and enum definitions
  • Async Support: Non-blocking API calls using httpx

Quick Start

Prerequisites

  • Python 3.10 or higher
  • uv package manager (recommended) or pip

Installation

# Clone the repository
git clone https://github.com/Ukenn2112/BangumiMCP.git
cd BangumiMCP

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

Configuration for Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bangumi-tv": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/BangumiMCP",
        "run",
        "main.py"
      ],
      "env": {
        "BANGUMI_TOKEN": "your_token_here"
      }
    }
  }
}

Note: BANGUMI_TOKEN is optional but required for:

  • Authenticated operations (collections, personal data)
  • R18 content access
  • Write operations (create, update, delete)

Get your token at: https://next.bgm.tv/demo/access-token

Project Architecture

BangumiMCP follows a modular architecture designed for maintainability and scalability:

BangumiMCP/
├── main.py                           # Server initialization (44 lines)
├── src/
│   ├── config.py                     # Configuration constants
│   ├── enums.py                      # API enum definitions (8 types)
│   ├── utils/
│   │   ├── api_client.py             # HTTP client & error handling
│   │   └── formatters.py             # Data formatting utilities
│   ├── resources/
│   │   └── openapi_resource.py       # OpenAPI specification resource
│   ├── tools/                        # 55 MCP tools organized by domain
│   │   ├── subject_tools.py          # Subjects & episodes (10 tools)
│   │   ├── character_tools.py        # Characters (7 tools)
│   │   ├── person_tools.py           # Persons & companies (7 tools)
│   │   ├── user_tools.py             # User information (3 tools)
│   │   ├── collection_tools.py       # Collections (11 tools)
│   │   ├── revision_tools.py         # Edit history (8 tools)
│   │   └── index_tools.py            # Indices/directories (9 tools)
│   └── prompts/
│       └── workflow_prompts.py       # Composite prompts (3)
├── bangumi-tv-api.json               # OpenAPI 3.0.3 specification
└── pyproject.toml                    # Project metadata

Available Tools

Subjects & Episodes (10 tools)

  • get_daily_broadcast - Weekly broadcast schedule
  • search_subjects - Full-text search with filters
  • browse_subjects - Category-based browsing
  • get_subject_details - Detailed subject information
  • get_subject_image - Subject image URL
  • get_subject_persons - Related creators/staff
  • get_subject_characters - Related characters
  • get_subject_relations - Related subjects
  • get_episodes - Episode list
  • get_episode_details - Episode information

Characters (7 tools)

  • search_characters - Character search
  • get_character_details - Character information
  • get_character_image - Character image URL
  • get_character_subjects - Subjects featuring character
  • get_character_persons - Voice actors & creators
  • collect_character - Add to favorites ⚠️ Requires auth
  • uncollect_character - Remove from favorites ⚠️ Requires auth

Persons (7 tools)

  • search_persons - Search creators/actors
  • get_person_details - Person information
  • get_person_image - Person image URL
  • get_person_subjects - Works by person
  • get_person_characters - Characters associated
  • collect_person - Add to favorites ⚠️ Requires auth
  • uncollect_person - Remove from favorites ⚠️ Requires auth

Users (3 tools)

  • get_user_info - Public user profile
  • get_user_avatar - User avatar URL
  • get_current_user - Authenticated user info ⚠️ Requires auth

Collections (11 tools)

  • get_user_collections - User's subject collections
  • get_user_subject_collection - Subject collection status
  • update_subject_collection - Update subject status ⚠️ Requires auth
  • get_user_episode_collection - Episode watch list ⚠️ Requires auth
  • update_episode_collection - Batch update episodes ⚠️ Requires auth
  • get_single_episode_collection - Single episode status ⚠️ Requires auth
  • update_single_episode_collection - Update single episode ⚠️ Requires auth
  • get_user_character_collections - Character collections
  • get_user_character_collection - Character collection status
  • get_user_person_collections - Person collections
  • get_user_person_collection - Person collection status

Revisions (8 tools)

  • get_person_revisions - Person edit history
  • get_person_revision - Single person edit detail
  • get_character_revisions - Character edit history
  • get_character_revision - Single character edit detail
  • get_subject_revisions - Subject edit history
  • get_subject_revision - Single subject edit detail
  • get_episode_revisions - Episode edit history
  • get_episode_revision - Single episode edit detail

Indices (9 tools)

  • create_index - Create new index ⚠️ Requires auth
  • get_index - Index details
  • update_index - Update index info ⚠️ Requires auth
  • get_index_subjects - Subjects in index
  • add_subject_to_index - Add subject ⚠️ Requires auth
  • update_index_subject - Update subject info ⚠️ Requires auth
  • remove_subject_from_index - Remove subject ⚠️ Requires auth
  • collect_index - Add index to collection ⚠️ Requires auth
  • uncollect_index - Remove index from collection ⚠️ Requires auth

Workflow Prompts

Pre-built multi-step workflows for common tasks:

  • search_and_summarize_anime - Search anime by keyword and get AI summary
  • get_subject_full_info - Get comprehensive subject information (details, persons, characters, relations)
  • find_voice_actor - Search character and identify voice actors

Development

Adding New Tools

  1. Identify the appropriate category (subject, character, person, etc.)
  2. Add the tool function to the corresponding file in src/tools/
  3. Register the tool in the module's register() function
  4. Update this README with the new tool count

Testing

# Test imports
python -c "from src.config import BANGUMI_TOKEN; print('OK')"
python -c "from src.tools import subject_tools; print('OK')"

# Run the server
uv run main.py

Code Structure

Dependency Hierarchy (no circular imports):

  • Level 0: config.py, enums.py (no dependencies)
  • Level 1: utils/ (depends on config & enums)
  • Level 2: resources/, tools/, prompts/ (depend on utils)
  • Level 3: main.py (orchestrates everything)

Import Guidelines:

  • Use relative imports within src/ package (e.g., from ..config import)
  • Import from specific modules, not package level
  • Follow the dependency hierarchy to avoid circular imports

Environment Variables

VariableRequiredDescription
BANGUMI_TOKENNoBangumi Access Token for authenticated operations and R18 content

License

This project is built on the Bangumi API documentation and follows its terms of service.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

中文

一个基于 Model Context Protocol (MCP) 的服务器，为 Bangumi TV API 提供程序化访问接口，使 Claude 等 AI 助手能够与海量的动画、漫画、音乐、游戏和真人影视数据进行交互。

功能特性

  • 55 个 MCP 工具：完整覆盖 Bangumi API 端点
  • 3 个工作流提示：预构建的多步骤工作流，用于常见任务
  • 1 个资源：完整的 OpenAPI 规范文档
  • 模块化架构：清晰、可维护的代码库，遵循 MCP 最佳实践
  • 类型安全：完整的 Python 类型提示和枚举定义
  • 异步支持：使用 httpx 的非阻塞 API 调用

快速开始

前置要求

  • Python 3.10 或更高版本
  • uv 包管理器（推荐）或 pip

安装

# 克隆仓库
git clone https://github.com/Ukenn2112/BangumiMCP.git
cd BangumiMCP

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖
uv pip install -e .

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "bangumi-tv": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/BangumiMCP",
        "run",
        "main.py"
      ],
      "env": {
        "BANGUMI_TOKEN": "your_token_here"
      }
    }
  }
}

注意：BANGUMI_TOKEN 是可选的，但以下操作需要：

  • 认证操作（收藏、个人数据）
  • 访问 R18 内容
  • 写操作（创建、更新、删除）

获取令牌：https://next.bgm.tv/demo/access-token

项目架构

BangumiMCP 采用模块化架构，便于维护和扩展：

BangumiMCP/
├── main.py                           # 服务器初始化（44 行）
├── src/
│   ├── config.py                     # 配置常量
│   ├── enums.py                      # API 枚举定义（8 种类型）
│   ├── utils/
│   │   ├── api_client.py             # HTTP 客户端和错误处理
│   │   └── formatters.py             # 数据格式化工具
│   ├── resources/
│   │   └── openapi_resource.py       # OpenAPI 规范资源
│   ├── tools/                        # 55 个 MCP 工具，按领域组织
│   │   ├── subject_tools.py          # 条目和章节（10 个工具）
│   │   ├── character_tools.py        # 角色（7 个工具）
│   │   ├── person_tools.py           # 人物和公司（7 个工具）
│   │   ├── user_tools.py             # 用户信息（3 个工具）
│   │   ├── collection_tools.py       # 收藏（11 个工具）
│   │   ├── revision_tools.py         # 编辑历史（8 个工具）
│   │   └── index_tools.py            # 目录（9 个工具）
│   └── prompts/
│       └── workflow_prompts.py       # 组合提示（3 个）
├── bangumi-tv-api.json               # OpenAPI 3.0.3 规范
└── pyproject.toml                    # 项目元数据

可用工具

条目和章节（10 个工具）

  • get_daily_broadcast - 每周放送时间表
  • search_subjects - 全文搜索，支持过滤
  • browse_subjects - 按分类浏览
  • get_subject_details - 详细条目信息
  • get_subject_image - 条目图片 URL
  • get_subject_persons - 相关创作者/制作人员
  • get_subject_characters - 相关角色
  • get_subject_relations - 相关条目
  • get_episodes - 章节列表
  • get_episode_details - 章节信息

角色（7 个工具）

  • search_characters - 角色搜索
  • get_character_details - 角色信息
  • get_character_image - 角色图片 URL
  • get_character_subjects - 角色出现的条目
  • get_character_persons - 声优和创作者
  • collect_character - 添加到收藏 ⚠️ 需要认证
  • uncollect_character - 从收藏中移除 ⚠️ 需要认证

人物（7 个工具）

  • search_persons - 搜索创作者/演员
  • get_person_details - 人物信息
  • get_person_image - 人物图片 URL
  • get_person_subjects - 人物参与的作品
  • get_person_characters - 关联的角色
  • collect_person - 添加到收藏 ⚠️ 需要认证
  • uncollect_person - 从收藏中移除 ⚠️ 需要认证

用户（3 个工具）

  • get_user_info - 公开用户资料
  • get_user_avatar - 用户头像 URL
  • get_current_user - 当前认证用户信息 ⚠️ 需要认证

收藏（11 个工具）

  • get_user_collections - 用户的条目收藏
  • get_user_subject_collection - 条目收藏状态
  • update_subject_collection - 更新条目状态 ⚠️ 需要认证
  • get_user_episode_collection - 章节观看列表 ⚠️ 需要认证
  • update_episode_collection - 批量更新章节 ⚠️ 需要认证
  • get_single_episode_collection - 单个章节状态 ⚠️ 需要认证
  • update_single_episode_collection - 更新单个章节 ⚠️ 需要认证
  • get_user_character_collections - 角色收藏
  • get_user_character_collection - 角色收藏状态
  • get_user_person_collections - 人物收藏
  • get_user_person_collection - 人物收藏状态

修订历史（8 个工具）

  • get_person_revisions - 人物编辑历史
  • get_person_revision - 单个人物编辑详情
  • get_character_revisions - 角色编辑历史
  • get_character_revision - 单个角色编辑详情
  • get_subject_revisions - 条目编辑历史
  • get_subject_revision - 单个条目编辑详情
  • get_episode_revisions - 章节编辑历史
  • get_episode_revision - 单个章节编辑详情

目录（9 个工具）

  • create_index - 创建新目录 ⚠️ 需要认证
  • get_index - 目录详情
  • update_index - 更新目录信息 ⚠️ 需要认证
  • get_index_subjects - 目录中的条目
  • add_subject_to_index - 添加条目 ⚠️ 需要认证
  • update_index_subject - 更新条目信息 ⚠️ 需要认证
  • remove_subject_from_index - 移除条目 ⚠️ 需要认证
  • collect_index - 收藏目录 ⚠️ 需要认证
  • uncollect_index - 取消收藏目录 ⚠️ 需要认证

工作流提示

预构建的多步骤工作流，用于常见任务：

  • search_and_summarize_anime - 按关键字搜索动画并获取 AI 摘要
  • get_subject_full_info - 获取全面的条目信息（详情、人物、角色、关联）
  • find_voice_actor - 搜索角色并识别声优

开发

添加新工具

  1. 确定合适的类别（条目、角色、人物等）
  2. 将工具函数添加到 src/tools/ 中相应的文件
  3. 在模块的 register() 函数中注册工具
  4. 更新此 README 中的工具数量

测试

# 测试导入
python -c "from src.config import BANGUMI_TOKEN; print('OK')"
python -c "from src.tools import subject_tools; print('OK')"

# 运行服务器
uv run main.py

代码结构

依赖层次结构（无循环导入）：

  • Level 0: config.py, enums.py（无依赖）
  • Level 1: utils/（依赖 config 和 enums）
  • Level 2: resources/, tools/, prompts/（依赖 utils）
  • Level 3: main.py（协调所有模块）

导入指南：

  • 在 src/ 包内使用相对导入（例如 from ..config import）
  • 从特定模块导入，而不是包级别
  • 遵循依赖层次结构以避免循环导入

环境变量

变量必填说明
BANGUMI_TOKEN否Bangumi 访问令牌，用于认证操作和访问 R18 内容

许可证

此项目基于 Bangumi API 文档构建，并遵循其服务条款。

相关项目

贡献

欢迎贡献！请随时提交问题或拉取请求。

致谢

此项目基于 Bangumi API 文档构建。