anime-mcp-server

---

概览

来自 AniList、Jikan（MyAnimeList）和 Kitsu 的动漫与漫画数据。搜索作品，获取包含 AniList 和 MAL 并列评分的完整详情，查看系列关联图谱，查询播出安排，以及查找角色、配音演员和工作室作品目录。

工具

工具	描述
anime_search_media	按标题、类型、标签、季度、年份、格式或状态搜索动漫或漫画。返回按相关性排序的结果，包含 ID、标题、评分、格式以及集数／章节数。优先使用 AniList；仅按标题查询且 AniList 无匹配结果时，回退到 Jikan（MAL）。
anime_get_media	根据 AniList ID 获取一部动漫或漫画的完整详情——简介、格式、集数／章节数、状态、季度、制作公司、原作、类型和标签（标记剧透）、并列显示的 AniList 和 MAL 评分、流媒体链接、封面／横幅以及直接关联作品。
anime_get_relations	在指定跳数限制内遍历关联作品图。按关联优先级、再按年份对主要和补充条目分组；并非严格的时间顺序。
anime_get_schedule	获取某一季度或未来剧集时间窗口的播出日程。季度模式会列出指定季度／年份播出的所有动漫。即将播出模式会返回日期窗口内每部播出作品的下一集，包含 UTC 时间戳和倒计时。
anime_find_characters	获取某部作品的角色和配音演员，或按姓名查找角色／配音演员。返回角色及其定位（主要／配角／背景角色）、各语言的配音演员，以及指向其他作品的交叉链接。
anime_get_recommendations	获取 AniList 推荐及对应的 Jikan（MAL）投票数。可选择附带用户喜欢源作品的原因，为推荐内容提供背景。
anime_get_rankings	获取总榜、趋势榜或季度榜。可按类型、标签和格式筛选。总榜按评分返回历史排名；趋势榜采用 AniList 的趋势排序；季度榜返回当前或指定季度按人气排序的作品。
anime_get_studio	按名称或 AniList 制作公司 ID 获取该制作公司的完整作品目录——该公司制作的所有作品均可按年份或评分排序，并显示格式、状态和集数。

资源

资源	描述
anime://media/{id}	根据 AniList ID 获取精简作品记录——标题、简介、评分、类型、流媒体数量和封面图。可用于注入上下文的稳定 URI。

所有资源数据也可通过工具获取。使用 anime_search_media 查找 AniList ID，然后再获取资源 URI。

---

功能参考

anime_search_media _工具

• 按标题、类型、标签、季度／年份、格式、状态或最多 5 个排序值搜索动漫或漫画；必须至少提供一个条件。使用 page／per_page 翻页（最多 50 条），并设置 include_adult: true 以包含成人作品
• 结果包含 AniList ID、标题、评分以及集数／章节数。优先使用 AniList；仅按标题搜索且无匹配结果时，可回退到 Jikan，但 per_page 必须为 25 或更少。请检查 has_next_page；只有在最后一页时，total_results 才是精确值
• AniList 的搜索、季度和排名结果最多只提供前 5,000 条；更深的页面会因 page_depth_exceeded 而失败，因此请缩小搜索条件范围

---

anime_get_media _工具

• 根据 AniList id 获取完整详情；成人内容需要设置 include_adult: true；请通过 anime_search_media 查找 ID
• 返回简介、类型、标记剧透的标签、制作公司、直接关联作品、图片、流媒体链接，以及分别列出的 AniList／MAL 评分。data_sources 会标明成功获取补充信息的数据源；若 ID 无法解析，则返回 not_found
• full_text: true 会以带围栏的 JSON 返回完整结果；默认情况下，简介为 500 个字符的预览，标签和关联作品会缩略显示，并附上省略内容的数量

anime_get_relations _工具

• 从 AniList id 开始遍历整个系列，最多遍历 max_depth 跳（默认值为 2，最大值为 4）
• 返回 main 和 supplementary 条目，包含季度年份以及集数／章节数，并按关系优先级和年份排序。not_found 表示未能解析根 ID
• depth、parent_id、relation_to_parent 和 path 展示到达每个条目的最短路径。仅直接关联根条目的条目会设置 relation_to_root，其他情况为 null。到达跳数上限的条目不会返回自身的关系；depth_reached 表示返回结果中的最深跳数

---

anime_get_schedule _工具

• season 模式需要 season 和 season_year；upcoming 模式使用 days_ahead（默认值为 7，最大值为 30）。使用 page／per_page 分页（最大值为 50）；成人作品需要设置 include_adult: true
• 返回 UTC ISO 8601 播出时间和 time_until_airing_seconds。请根据 has_next_page 翻页；只有在季度模式的最后一页，total_results 才是精确值。invalid_season 和 conflicting_inputs 用于标识无效的模式输入

---

anime_find_characters _工具

• 在媒体 id、character_name 或 voice_actor_name 中恰好提供一项。language 仅用于筛选媒体演员列表；per_page 上限为 25
• 根据 mode 返回演员、配音演员或媒体出演信息。truncated: true 会在演员列表达到上限时提供翻页指引；media_not_found／not_found 用于区分未知媒体 ID 和未匹配的名称
• voice_actor_data_available: false 表示数据提供方没有配音演员数据，而非列表为空。full_text: true 会以带围栏的 JSON 返回当前页中的所有角色和完整简介；默认情况下，简介为 500 个字符的预览，工作人员角色最多返回 20 个，并提供被省略内容的计数

---

anime_get_recommendations _工具

• 获取 AniList id 的推荐结果，使用 page／per_page 分页（最大值为 25）；可选的 liked_aspects 会原样回显
• 分别返回 anilist_rating 和 jikan_votes，并通过 sources 标明各项数据来源。truncated: true 会提供翻页指引；not_found 表示未能解析来源 ID

---

anime_get_rankings _工具

• 对 ANIME 或 MANGA 的 top／trending 排名；seasonal 和季度／年份筛选仅适用于 ANIME（否则返回 anime_only_season）。仍可使用类型／标签／格式筛选，以及 page／per_page（最大值为 50）。成人作品需要设置 include_adult: true
• 条目包含从 1 开始的 rank 和 season_label。请根据 has_next_page 翻页；只有在最后一页，total_results 才是精确值。季节模式需同时提供 season 和 season_year，或两者均不提供以使用当前季度（否则返回 invalid_season）

---

anime_get_studio _工具

• 在 name 或 id 中恰好提供一项以确定工作室；按人气、评分或发布日期排序，并使用 page／per_page 分页（最大值为 25）
• 每个不同作品在页面中返回一行，is_main_studio 用于标识主要制作人员信息。请根据 has_next_page 翻页；只有当完整作品目录在第 1 页内时，total_titles 才是精确值。not_found 表示未能解析工作室

---

anime://media/{id} _资源

• 使用来自 anime_search_media 或 anime_get_media 的 AniList id，读取精简的 application/json 媒体记录
• ID 必须是 1 至 2147483647 之间的整数；任何其他值都会在调用上游之前因 invalid_id 失败
• 返回标题变体、概要、评分、类型、流媒体数量和封面图片；如需标签、工作室、流媒体链接和关联信息，请使用 anime_get_media

---

功能特性

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及结构化日志记录，并可选启用 OpenTelemetry 跟踪。

动漫/漫画专属功能：

• 三来源架构：AniList GraphQL（主要来源）、Jikan v4 REST（MAL 评分和推荐）、Kitsu JSON:API（含字幕/配音语言详情的流媒体链接）
• 通过 AniList 的 idMal 桥接 ID，进行 ID 对应——无需猜测不同来源之间的 ID
• 遍历系列关系图，按关系类型优先级进行启发式排序，再按季度年份排序
• 感知速率限制的服务层：AniList 每 30 秒 30 个请求，并自动退避；Jikan 调用间隔至少为 350 毫秒
• 从设计上无需密钥——这三个来源均为公共服务，无需 API 凭据

便于 Agent 使用的输出：

• 分别呈现双评分——AniList meanScore（0–100）和 MAL score（0–10），并附上样本数（scored_by），方便 Agent 判断权重；绝不混合计算综合评分
• 剧透标记——标签摘要会隐藏剧透/成人标签；结构化输出和 full_text: true 会包含所有带标记的标签
• 补充数据来源——anime_get_media.data_sources 会报告是否已获取 AniList、MAL/Jikan 和 Kitsu 数据；无法获取的补充数据对应标记为 false
• 全程使用 UTC 时间戳；同时回显季度标签（WINTER 2024），避免冬季/春季/夏季/秋季的季度边界问题

---

开始使用

无需 API 密钥——所有三个上游来源（AniList、Jikan、Kitsu）均为无需密钥的公共 API。

将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "anime-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/anime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "anime-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/anime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "anime-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/anime-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置要求

• Bun v1.4.0 或更高版本（或 Node.js v24+）。无需 API 密钥。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/anime-mcp-server.git

2. 进入目录：

cd anime-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# edit .env if you want to change transport or log level

---

配置

无需设置服务专属环境变量。所有框架变量均为可选项，并提供合理的默认值。

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_HOST	HTTP 服务主机名。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	MCP 服务的端点路径。	/mcp
MCP_SESSION_MODE	会话模式：auto、stateful 或 stateless。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）：debug、info、notice、warning、error。	info
LOG_TOOL_FAILURE_PAYLOADS	记录失败调用的参数和结果；按键名脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 字节（默认 16384）。自由格式值中的机密信息不会脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 检测。	false

完整的可选覆盖项列表请参阅 .env.example。

---

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t anime-mcp-server .
docker run --rm -p 3010:3010 anime-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/anime-mcp-server。默认安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

---

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具、资源并初始化服务。
src/mcp-server/tools	工具定义（*.tool.ts）。
src/mcp-server/resources	资源定义（*.resource.ts）。
src/services/anilist	AniList GraphQL 客户端——所有查询的主要数据源。
src/services/jikan	Jikan v4 REST 客户端——提供 MAL 评分和推荐。
src/services/kitsu	Kitsu JSON:API 客户端——提供带有字幕／配音语言详情的流媒体链接。
tests/	与 src/ 结构对应的单元测试和集成测试。
changelog/	按版本划分的变更日志文件（changelog/<minor>.x/<version>.md）。

---

开发指南

开发指南和架构规则请参阅 CLAUDE.md/AGENTS.md。简要说明：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 进行租户级存储
• 通过 src/mcp-server/*/definitions/index.ts 中的汇总文件注册新工具和资源
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段
• AniList 是主要数据源——通过 Promise.allSettled 优雅处理补充数据源（Jikan、Kitsu）的故障

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0——详情请参阅 LICENSE。