Bangumi

License Python Version MCP

中文版本

A Model Context Protocol (MCP) server for accessing Bangumi API

Bangumi MCP is a Model Context Protocol (MCP) server that provides access to the Bangumi API, allowing users to search for and retrieve information about anime, manga, and other related content.

Features

The Bangumi MCP server provides a comprehensive set of tools for interacting with the Bangumi API, including:

The project tracks the Bangumi OpenAPI schema bundled in bangumi_mcp/dist.json and currently targets the 2026-05-2 API schema. It requires mcp>=1.27.2 and uses modern MCP features such as tool output schemas, structured tool results, tool annotations, and Streamable HTTP.

Calendar and Time

• get_current_time: Get the current time
• get_calendar: Get the weekly broadcast schedule

Subject Tools

• search_subjects: Search for subjects with various filters
• get_subjects: Browse subjects by type and category
• get_subject_info: Get detailed information about a specific subject
• get_subject_image: Get a subject image URL
• get_subject_persons: Get person information for a subject
• get_subject_characters: Get character information for a subject
• get_subject_relations: Get related subjects

Episode Tools

• get_episodes: Get episode information for a subject
• get_episode_info: Get detailed information about a specific episode

Revision Tools

• get_subject_revisions: Get subject revision history
• get_subject_revision_info: Get subject revision details
• get_episode_revisions: Get episode revision history
• get_episode_revision_info: Get episode revision details
• get_character_revisions: Get character revision history
• get_character_revision_info: Get character revision details
• get_person_revisions: Get person revision history
• get_person_revision_info: Get person revision details

Character Tools

• search_characters: Search for characters
• get_character_info: Get detailed character information
• get_character_image: Get a character image URL
• get_character_subjects: Get subjects related to a character
• get_character_persons: Get persons related to a character
• post_character_collection: Collect a character

Person Tools

• search_persons: Search for persons
• get_person_info: Get detailed person information
• get_person_image: Get a person image URL
• get_person_subjects: Get subjects related to a person
• get_person_characters: Get characters related to a person
• post_person_collection: Collect a person

Index Tools

• post_index: Create an index for the current user
• get_index_info: Get index information
• put_index: Update index information
• post_index_collection: Collect an index
• delete_index_collection: Uncollect an index
• get_index_subjects: Get subjects in an index
• post_index_subject: Add a subject to an index
• put_index_subject: Update a subject in an index
• delete_index_subject: Delete a subject from an index

User Tools

• get_user_info: Get user information
• get_user_avatar: Get a user avatar URL
• get_me_info: Get current user information

Collection Tools

• get_user_collections: Get user's subject collections
• get_user_collection_info: Get user's collection info for a specific subject
• post_my_collection: Collect a subject for the current user
• patch_my_collection: Update a subject collection for the current user
• get_my_episode_collections: Get current user's episode collections
• patch_my_episode_collections: Update current user's episode collection
• get_my_episode_collection_info: Get current user's episode collection info for a specific episode
• put_my_episode_collection_info: Update current user's episode collection
• get_user_character_collections: Get user's character collections
• get_user_character_collection_info: Get user's character collection info for a specific character
• get_user_person_collections: Get user's person collections
• get_user_person_collection_info: Get user's person collection info for a specific person

Installation

1. Clone the repository:

   git clone https://github.com/etherwindy/Bangumi-MCP.git
   cd Bangumi-MCP
   

2. Install dependencies:

   It is recommended to use uv. The project includes a standard build configuration, so the bangumi-mcp console script is available after syncing:

   uv sync
   uv run bangumi-mcp --help
   

   You can also install it into another environment with uv pip install -e ..

Server Configuration

The Bangumi MCP server requires a Bangumi API token for full functionality. If you use SSE or streamable HTTP, you need to configure this token before the server starts:

Method 1: Using a .env file (Recommended)

Create a .env file in the project root directory with your Bangumi API token:

BANGUMI_API_TOKEN=your_api_token_here

Method 2: Using Environment Variables

Set the environment variable directly in your terminal:

export BANGUMI_API_TOKEN=your_api_token_here

On Windows, use:

set BANGUMI_API_TOKEN=your_api_token_here

Usage

STDIO

Import this JSON config into your MCP client application, such as Cherry Studio:

{
    "mcpServers": {
        "Bangumi-MCP": {
            "command": "uv",
            "args": [
                "--directory",
                "{your_path_to_the_folder}/Bangumi-MCP",
                "run",
                "bangumi-mcp"
            ],
            "env": {
                "BANGUMI_API_TOKEN": "your_token_here"
            }
        }
    }
}

SSE

By default, the server will run on localhost:18080. You can specify a different host and port using the --host and --port arguments:

cd Bangumi-MCP
uv run bangumi-mcp --mode=sse --host localhost --port 18080

Configure your MCP client application, for example:

{
   "mcpServers": {
      "Bangumi-MCP": {
         "type": "sse",
         "url": "http://localhost:18080/sse"
      }
   }
}

Streamable HTTP

By default, the server will run on localhost:18080. You can specify a different host and port using the --host and --port arguments:

cd Bangumi-MCP
uv run bangumi-mcp --mode=streamable_http --host localhost --port 18080

Configure your MCP client application, for example:

{
   "mcpServers": {
      "Bangumi-MCP": {
         "type": "streamableHttp",
         "url": "http://localhost:18080/mcp/"
      }
   }
}

Modern MCP Support

• Tool responses include structuredContent when the underlying tool returns structured JSON data, while still including readable JSON text for compatibility.
• Tool metadata includes MCP annotations such as readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.
• The server supports STDIO, SSE, and Streamable HTTP transports.
• Mutating tools require a valid BANGUMI_API_TOKEN; read-only public API tools can be used without a token where Bangumi allows it.

Acknowledgements

This project was built with the assistance of Qwen3-Coder and Claude Sonnet 4.

License

This project is licensed under the MIT License. See the LICENSE file for details.