MAL MCP Server

MAL MCP 服务

适用于 MyAnimeList 的 MCP 服务。它可与任何兼容 MCP 的客户端或 Agent（Claude Desktop/Code、Cursor、VS Code、Cline、Continue 等）配合使用，因为该服务使用标准 MCP stdio 协议。

功能

它使用混合后端：

• 读取 → Tenrai（免费、非官方的 MAL API）。 搜索、详情、排名、季度、新角色、推荐和评论。无需凭据。
• 你的个人列表 → 官方 MyAnimeList API。 读取、更新和删除你个人动漫／漫画列表中的条目。需要登录一次（见下文）。

所需内容及其用途

开始使用无需准备任何东西。你可以直接跳到 安装。以下内容均为可选，每完成一步都会增加更多功能：

你设置……	你将获得……
（什么也不设置）	搜索、详情、排名、季度、新角色、评论等。立即可用，无需注册。
MyAnimeList Client ID（2 分钟，免费 →）	除上述功能外，还有：11 个读取工具（搜索、排名、季度、推荐、详情、统计数据）可在 Tenrai（默认读取后端）发生故障时继续使用。它们会改用官方 MyAnimeList API 重试。仍然无需登录。
上述 Client ID，再加上运行一次 login_mal 工具（同一操作指南 →）	除上述全部功能外，还可以使用你自己的 MyAnimeList 列表：查看列表、添加／更新条目、标记已观看、删除条目。

如果没有登录，个人列表工具会回复一条清晰的消息，告诉你如何获取登录权限。其他功能仍会照常运行。

示例查询

连接后，只需用自然语言向你的 Agent 提问。

无需凭据（搜索、详情、排行榜、季度、角色等）：

"Search for the anime Frieren and show its score, studio and synopsis."
"What are the top 10 anime of all time?"
"What's airing this season? Sort by popularity."
"Recommend anime similar to Steins;Gate."
"What are people saying in reviews of Chainsaw Man?"
"Show the main characters and Japanese voice actors of Cowboy Bebop."
"When does the next episode of One Piece air?"
"Give me the top manga in the Romance genre."
"What's on the upcoming season's schedule?"
"Pick a random highly-rated anime for me."

使用 MyAnimeList 账号（一次性执行 login_mal 后；参见 连接 MyAnimeList 账号以使用个人列表工具）：

"Show my MAL profile and watching stats."
"What's on my anime list that I marked as watching?"
"Add Frieren to my plan-to-watch list."
"Set Cowboy Bebop to completed with a score of 9."
"Bump my episode count for One Piece to 1095."
"Remove Bleach from my manga list."

工具

工具	后端	身份验证
search_anime, search_manga	Tenrai	无
get_anime, get_manga	Tenrai	无
get_anime_characters, get_anime_recommendations, get_anime_reviews	Tenrai	无
get_manga_characters, get_manga_recommendations, get_manga_reviews	Tenrai	无
get_recent_anime_recommendations, get_recent_manga_recommendations	Tenrai	无
get_anime_episodes, get_anime_videos	Tenrai	无
get_anime_genres, get_manga_genres	Tenrai	无
search_characters, get_character	Tenrai	无
search_people, get_person, get_anime_staff	Tenrai	无
get_anime_statistics, get_manga_statistics	Tenrai	无
get_random_anime, get_random_manga, get_random_character, get_random_person	Tenrai	无
get_anime_news, get_manga_news, get_news	Tenrai	无
get_top_anime, get_top_manga	Tenrai	无
get_top_people, get_top_characters	Tenrai	无
get_seasonal_anime, get_upcoming_season, get_seasons_list, get_anime_schedule	Tenrai	无
get_producers, get_producer, get_magazines	Tenrai	无
get_interest_stacks, get_interest_stack, get_anime_interest_stacks, get_manga_interest_stacks	Tenrai	无
get_my_user_info, get_my_anime_list, get_my_manga_list	MAL	令牌
update_my_anime_status, update_my_manga_status	MAL	令牌
delete_my_anime_list_item, delete_my_manga_list_item	MAL	令牌
login_mal, submit_mal_redirect	MAL	登录

token = 需要登录 MyAnimeList（运行一次 login_mal）。提示词： recommend_similar、seasonal_overview、hidden_gems。recommend_similar 的 标题为可选项：省略后，它会询问你指的是哪部动漫。支持提示词参数补全的客户端会在你输入时提供实时标题建议 （从第三个字符开始；非拉丁文字标题则从第二个字符开始）。

安装

作为 .mcpb 捆绑包（一键安装，例如 Claude Desktop）

下载 mal-mcp.mcpb （始终是最新版本），并使用你的 MCP 客户端打开。系统会提示你输入可选的 MyAnimeList Client ID。设置后，运行 login_mal 工具即可启用个人列表 工具（请参阅连接 MyAnimeList 账号以使用个人列表工具）。 留空则只能使用无需凭据的读取工具。

从源代码构建

git clone https://github.com/Grinv/mal-mcp
cd mal-mcp
npm ci
npm run build

这会生成一个独立的 dist/index.js。将客户端指向该文件（见下文）。

连接到 MCP 客户端

将服务添加到客户端的 MCP 配置中（Claude Desktop/Code、Cursor、VS Code、 Cline 等）。最简单的方式是使用 npx，无需克隆或构建。它使用系统上的 Node， 版本必须为 22.18 或更高（node -v）；上述 .mcpb 捆绑包则使用客户端内置的 Node：

{
  "mcpServers": {
    "mal": {
      "command": "npx",
      "args": ["-y", "mal-mcp"],
      "env": {
        "MAL_CLIENT_ID": "..."
      }
    }
  }
}

也可以使用 Claude Code CLI：

claude mcp add mal -e MAL_CLIENT_ID=... -- npx -y mal-mcp

如果你是从源代码构建的，请将 "command": "npx", "args": ["-y", "mal-mcp"] 替换为 "command": "node", "args": ["/absolute/path/to/mal-mcp/dist/index.js"]。

env 代码块是可选的。省略它即可只使用无需凭据的读取 工具（搜索、详情、排行榜等）；登录前，个人列表工具会返回明确的 错误。要启用这些工具，请设置 MAL_CLIENT_ID，并运行一次 login_mal 工具（只需通过浏览器授权一次；之后令牌会自动存储并刷新）。 服务不会读取 .env 文件，因此请通过此 env 代码块（或你的 shell 环境）传递配置。请参阅 docs/auth.md，了解完整的登录流程；另请参阅 docs/clients.md，了解更多客户端。

连接 MyAnimeList 账户（用于个人列表工具）

搜索／浏览工具无需设置。要使用个人列表工具 （get_my_*、update_my_*、delete_my_*），请授权一次账户。整个过程 大约需要两分钟。无需客户端密钥：mal-mcp 使用现代的 公开客户端流程（PKCE），因此只需要 Client ID。

步骤 1：注册 MyAnimeList 应用（一分钟）。

1. 前往 https://myanimelist.net/apiconfig，然后点击 Create ID。
2. App Type： 选择 other。（不要选 web：该类型会强制要求客户端 密钥，而此服务不会使用它。）
3. App Redirect URL： 完整输入以下地址

   http://localhost:8080/callback
   

   （如果设备上的 8080 端口已被占用，请在此处选择其他端口，并将 MAL_OAUTH_PORT 设为相同的数字。请参阅配置。）
4. 其余必填字段填写合理内容，接受条款，然后点击 Submit。
5. 打开新建的应用并复制其 Client ID。

步骤 2：将 Client ID 提供给服务。

将其添加到 MCP 客户端配置中（或粘贴到 Claude Desktop 安装表单中）。 这里不需要做其他操作：

"env": { "MAL_CLIENT_ID": "paste-your-client-id-here" }

重启服务／客户端，使其读取该值。

步骤 3：登录（点击一次）。

在助手中运行 login_mal 工具（或直接说 “登录 MyAnimeList”）。它会回复 一个链接。打开链接，登录 MAL，然后点击 Allow。

• 在本地运行（Claude Desktop，或在自己的设备上运行 Claude Code）： 点击 Allow 后会自动完成登录。说 “显示我的 MAL 个人资料”，并通过 （get_my_user_info）确认。
• 在远程／SSH／无头主机上运行： 点击 Allow 后，浏览器会跳转到一个无法 加载的页面。这是正常情况。复制浏览器地址栏中的完整地址 （其中包含 ?code=…），并将其提供给 submit_mal_redirect 工具以完成登录。

就这么简单。令牌会保存在本地（~/.config/mal-mcp/tokens.json，0600）， 之后会自动刷新，因此你无需再次登录。

不想进行交互式操作？ 你可以改为预先设置 MAL_REFRESH_TOKEN （以及 MAL_CLIENT_ID），或设置独立的 MAL_ACCESS_TOKEN。有关如何手动获取令牌，请参阅 docs/auth.md。

配置

所有配置均通过环境变量完成，且都是可选的。即使没有凭据， 读取工具仍可使用。要使用个人列表工具，请设置 MAL_CLIENT_ID 并运行一次 login_mal 工具；之后会自动获取并刷新访问令牌。（mal-mcp 是公开的 PKCE 客户端，因此无需客户端密钥。）

变量	用途
MAL_CLIENT_ID	你的 MyAnimeList Client ID。有关如何获取，请参阅连接 MyAnimeList 账户（免费，约需 2 分钟，无需编写代码）。
MAL_REFRESH_TOKEN	高级选项，可选。 通过直接预先提供令牌，跳过交互式的 login_mal 步骤。大多数人不需要此选项。如需使用，请参阅 docs/auth.md。
MAL_ACCESS_TOKEN	高级选项，可选。 独立令牌，无需刷新即可使用约 30 天。请参阅 docs/auth.md。

调优（极少需要）

这些配置都有合理的默认值；只有在需要调整时间间隔、更换上游基础 URL，或要覆盖服务记录日志或存储令牌的位置／方式时才修改。

变量	用途
MAL_TOKEN_STORE	覆盖登录令牌在磁盘上的保存位置（默认：操作系统的配置文件夹）。
MAL_OAUTH_PORT	仅当端口 8080 已被本机上的其他程序占用时才需要设置。参见账号设置指南的第 1 步。
LOG_LEVEL	服务记录日志的详细程度：debug | info | warn | error | silent（默认 info）。日志仅写入 stderr。MCP 层没有日志功能，因此客户端无法通过 logging/setLevel 获取或筛选日志；请直接检查服务进程的 stderr。
TENRAI_MIN_INTERVAL_MS	Tenrai 调用之间的最短间隔（默认 300）。此外，客户端还会遵守 Tenrai 公布的每秒 4 次以及每分钟 120 次公共限制；设为 0 可禁用所有客户端限流。
CACHE_TTL_MS	内存读取缓存的 TTL（默认 300000 = 5 分钟）。
HTTP_TIMEOUT_MS、HTTP_RETRIES	单次请求超时时间（默认 15000）和瞬时故障时的重试次数（默认 2）。
TENRAI_BASE_URL、MAL_BASE_URL、MAL_OAUTH_BASE_URL	覆盖上游基础 URL。

请在 MCP 客户端配置的 env 块中提供这些变量（服务不会读取 .env 文件）。有关如何获取凭据，请参阅 docs/auth.md；有关客户端配置示例，请参阅 docs/clients.md。

NSFW 内容

默认不会过滤 NSFW（成人）结果。服务会返回上游 API 提供的所有内容。大多数读取工具都接受两个过滤级别：

• sfw: true：排除成人／明确分级的条目（R+ 轻度裸露及以上）。
• sfw_strict: true：还会排除所有标记为 Ecchi 类型的内容，即使这些作品本身属于主流且分级安全，单独使用 sfw 仍会将其放行（例如 No Game No Life、Kill la Kill）。

对于列表／搜索工具（search_anime、search_manga、get_seasonal_anime、get_upcoming_season、get_anime_schedule、get_top_anime、get_top_manga、get_random_anime、get_random_manga、get_recent_anime_recommendations、get_recent_manga_recommendations），此过滤器会筛选返回的条目。对于按 ID 查询的工具（get_anime、get_manga、get_anime_recommendations、get_manga_recommendations、get_character、get_person、get_anime_news、get_manga_news），无论如何都会返回你请求的条目。过滤器只会从该条目的嵌套列表中排除 NSFW 条目（例如动画的 relations、人物自己的动画／漫画作品列表）；但对于两个新闻工具，如果动画／漫画被评为 NSFW，则可能会清空整个结果。get_top_people／get_top_characters 没有此类过滤器，因为人物／角色不像动画／漫画那样有独立的内容分级。

search_anime 和 get_top_anime／get_seasonal_anime／get_upcoming_season 还接受 rating 过滤器，提供更精细的控制：可直接指定一个或多个 MAL 内容分级（例如 pg13、r17），而不是统一按成人内容界限过滤。

开发

npm run build        # type-check + bundle to dist/
npm test             # node:test suite (mocked, offline)
npm run test:coverage
npm run lint
npm run format
npm run check:api    # live health-check of upstream endpoints
npm run inspector    # run under the MCP Inspector

运行环境需要 Node ≥ 22.18。贡献者／Agent 指引请参阅 AGENTS.md。

更新

如需接收新版本通知，请在 GitHub 上点击 Watch → Releases。

• **.mcpb 捆绑包：**从 发布页面下载新的 mal-mcp.mcpb，并在 客户端中重新安装（新版本会替换旧版本）。
• **从源码安装：**运行 git pull && npm ci && npm run build。
• **npx（发布到 npm 后）：**未固定版本的 npx -y mal-mcp 会在下次运行时获取最新版本；如果固定了版本，请升级版本号。

每个版本的变更内容请参阅 CHANGELOG。

致谢与条款

这是一个非官方项目，与 MyAnimeList 无关联，也未获其认可。读取的数据由 Tenrai 提供，这是一个免费的非官方 MAL API；请遵守其速率限制。个人列表操作使用官方 MyAnimeList API，并使用你自己的账号和令牌。使用须遵守 MyAnimeList 服务条款。

隐私政策

mal-mcp 在你的设备本地运行，且自身不收集遥测数据。请参阅 PRIVACY.md，了解其具体处理哪些数据（包括个人列表工具可在你的真实 MyAnimeList 账号中读取和修改哪些内容）、向 Tenrai／MyAnimeList 发送哪些数据，以及会在磁盘上存储哪些内容（如有）。

安全

请参阅 SECURITY.md，了解读取／写入工具的区别、令牌存储、凭据脱敏，以及如何报告漏洞。

许可证

MIT © Grinv