MCP Service

Bangumi MCP サーバー

English | 中文

---

English

Bangumi TV API へのプログラムからのアクセスを提供する Model Context Protocol (MCP) サーバーです。Claude のような AI アシスタントが、アニメ、マンガ、音楽、ゲーム、および実世界のメディアに関する包括的なデータを扱えるようにします。

機能

• 55 個の MCP ツール: Bangumi API エンドポイントを完全にカバー
• 3 個のワークフロープロンプト: 一般的なタスク向けに構築済みのマルチステップワークフロー
• 1 個のリソース: API ドキュメント用の完全な OpenAPI 仕様
• モジュラーアーキテクチャ: MCP のベストプラクティスに従った、クリーンで保守しやすいコードベース
• 型安全: 完全な Python の型ヒントと列挙型定義
• 非同期サポート: httpx を使用したノンブロッキングな API 呼び出し

クイックスタート

前提条件

• Python 3.10 以上
• uv パッケージマネージャー (推奨) または pip

インストール

# 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 .

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                           # 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

利用可能なツール

サブジェクトとエピソード (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. 適切なカテゴリ（subject、character、person など）を特定します
2. src/tools/ 内の対応するファイルにツール関数を追加します
3. モジュールの register() 関数にツールを登録します
4. 新しいツール数でこの README を更新します

テスト

# 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

コード構造

依存関係の階層（循環インポートなし）：

• レベル 0: config.py、enums.py（依存関係なし）
• レベル 1: utils/（config と enums に依存）
• レベル 2: resources/、tools/、prompts/（utils に依存）
• レベル 3: main.py（全体を統括）

インポートのガイドライン：

• src/ パッケージ内では相対インポートを使用します（例：from ..config import）
• パッケージレベルではなく、特定のモジュールからインポートします
• 循環インポートを避けるため、依存関係の階層に従います

環境変数

変数	必須	説明
BANGUMI_TOKEN	いいえ	認証操作および R18 コンテンツ向けの Bangumi アクセストークン

ライセンス

このプロジェクトは Bangumi API ドキュメントに基づいて構築されており、その利用規約に従います。

関連プロジェクト

• BangumiMCP-ts - BangumiMCP の TypeScript 版

コントリビューション

コントリビューションを歓迎します！お気軽に issue や pull request を送信してください。

---

中文

一个基于 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 文档构建，并遵循其服务条款。

相关项目

• BangumiMCP-ts - BangumiMCP 的 TypeScript 版本

贡献

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

---

致谢

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