Bangumi MCP Server

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

| Variable | Required | Description |
|----------|----------|-------------|
| BANGUMI_TOKEN | No | Bangumi Access Token for authenticated operations and R18 content |

License

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

Related Projects

- BangumiMCP-ts - TypeScript version of BangumiMCP

Contributing

…