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. 適切なカテゴリ（作品、キャラクター、人物など）を特定する

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

コード構造

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

• 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 API ドキュメントに基づいて構築されており、その利用規約に従います。

関連プロジェクト

• BangumiMCP-ts - BangumiMCP の TypeScript 版

貢献

貢献を歓迎します！問題の報告やプルリクエストを気軽にお送りください。

Related MCP server: MyAnimeList MCP Server

中文

Bangumi TV API に基づく Model Context Protocol (MCP) サーバーであり、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 API ドキュメントに基づいて構築されており、その利用規約に従います。

関連プロジェクト

• BangumiMCP-ts - BangumiMCP の TypeScript 版

貢献

貢献を歓迎します！問題の報告やプルリクエストを気軽にお送りください。

致謝

このプロジェクトは Bangumi API ドキュメントに基づいて構築されています。