Bangumi MCP 서버

English | 中文

English

Bangumi TV API에 대한 프로그래밍 방식의 액세스를 제공하는 모델 컨텍스트 프로토콜(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

中文

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

相关项目

• BangumiMCP-ts - BangumiMCP 的 TypeScript 版本

贡献

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

致谢

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