AI导哈

Bangumi API访问工具

一个基于Model Context Protocol (MCP)的服务器，为Bangumi TV API提供程序化访问接口，使AI助手能够与海量的动画、漫画、音乐、游戏和真人影视数据进行交互。

  • by Ukenn2112
  • Python
  • 本地部署
  • 27 星标
  • 更新于
在 GitHub 查看 Ukenn2112/BangumiMCP

使用说明

Bangumi MCP服务器

英语 | 中文

英语

一种模型上下文协议（MCP）服务器，提供对 Bangumi电视台 API，使像Claude这样的人工智能助手能够与全面的动漫、漫画、音乐、游戏和现实世界的媒体数据进行交互。

特性

  • 55 MCP工具：全面覆盖Bangumi API端点
  • 3工作流提示：为常见任务预先构建多步骤工作流
  • 1资源：API文档的完整OpenAPI规范
  • 模块化架构：遵循MCP最佳实践的干净、可维护的代码库
  • 类型安全：完整的Python类型提示和枚举定义
  • 异步支持：使用httpx的非阻塞API调用

快速开始

先决条件

  • Python 3.10或更高版本
  • 紫外线 包管理器（推荐）或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桌面配置

添加到您的 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 -从集合中删除索引⚠️ 需要身份验证

工作流提示

为常见任务预先构建的多步骤工作流程：

  • 搜索和摘要_动漫 -按关键字搜索动漫，获取AI摘要
  • get_subject_full_info -获取全面的主题信息（细节、人物、人物、关系）
  • find_voice_ator -搜索角色并识别配音演员

发展

添加新工具

  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

代码结构

依赖层次结构 （无循环进口）：

  • 级别0： config.py, enums.py （无依赖关系）
  • 第一级： utils/ （取决于配置和菜单）
  • 第二级： resources/, tools/, prompts/ （取决于utils）
  • 第三级： main.py （协调一切）

进口指南:

  • 在内部使用相对进口 src/ 包装（例如。， from ..config import)
  • 从特定模块而非包级别导入
  • 遵循依赖关系层次结构以避免循环导入

环境变量

变量 必填 描述
BANGUMI_TOKEN 否 用于身份验证操作和R18内容的Bangumi访问令牌

许可证

本项目建立在Bangumi API文件的基础上，并遵循其服务条款。

相关项目

贡献

欢迎投稿！请随时提交问题或拉取请求。

中文

一个基于 Model Context Protocol (MCP) 的服务器，为 Bangumi电视台 API 提供程序化访问接口，使 Claude 等 AI 助手能够与海量的动画、漫画、音乐、游戏和真人影视数据进行交互。

功能特性

  • 55 个 MCP 工具：完整覆盖 Bangumi API 端点
  • 3 个工作流提示：预构建的多步骤工作流，用于常见任务
  • 1 个资源：完整的 OpenAPI 规范文档
  • 模块化架构：清晰、可维护的代码库，遵循 MCP 最佳实践
  • 类型安全：完整的 Python 类型提示和枚举定义
  • 异步支持：使用 httpx 的非阻塞 API 调用

快速开始

前置要求

  • Python 3.10 或更高版本
  • 紫外线 包管理器（推荐）或 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 - 取消收藏目录 ⚠️ 需要认证

工作流提示

预构建的多步骤工作流，用于常见任务：

  • 搜索和摘要_动漫 - 按关键字搜索动画并获取 AI 摘要
  • get_subject_full_info - 获取全面的条目信息（详情、人物、角色、关联）
  • find_voice_ator - 搜索角色并识别声优

开发

添加新工具

  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

代码结构

依赖层次结构（无循环导入）：

  • 级别0： config.py, enums.py（无依赖）
  • 第一级： utils/（依赖 config 和 enums）
  • 第二级： resources/, tools/, prompts/（依赖 utils）
  • 第三级： main.py（协调所有模块）

导入指南：

  • 在 src/ 包内使用相对导入（例如 from ..config import）
  • 从特定模块导入，而不是包级别
  • 遵循依赖层次结构以避免循环导入

环境变量

变量 必填 说明
BANGUMI_TOKEN 否 Bangumi 访问令牌，用于认证操作和访问 R18 内容

许可证

此项目基于 Bangumi API 文档构建，并遵循其服务条款。

相关项目

贡献

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

致谢

此项目基于 API班古米 文档构建。

相关 MCP