Mal MCP Server

mal-mcp服务器

一 MCP（模型上下文协议） 将AI助手连接到 MyAnimeList API v2.搜索动漫、浏览季节图表、查看排名、查找漫画——所有这些都可以从你的人工智能聊天中完成。

它做什么

此服务器向任何兼容MCP的客户端（Claude Desktop、Claude Code、Cursor等）公开7个只读工具：

所有工具都返回人类可读的格式化文本，包括分数、流派、概要、MAL链接等。

5列表返回工具支持 服务器端过滤 --流派、配乐、媒体类型、状态、来源等。服务器从MAL获取多达500个结果并在客户端进行过滤，因此AI只看到匹配的结果。这大大减少了过滤查询的上下文污染。

先决条件

• Node.js 18+（使用本地 fetch)
• A. MyAnimeList API客户端ID （免费，需要2分钟）

获取MAL客户ID

1. 首选 https://myanimelist.net/apiconfig/create （您需要一个MAL帐户）
2. 填写：

- 应用程序名称：您想要的任何内容（例如“我的MCP服务器”） - 应用程序类型：“其他” - 应用描述：任何内容（例如“用于动漫查找的个人MCP服务器”） - 应用重定向URL: http://localhost （不用于客户端ID身份验证，但该字段是必需的） - 你的家园：可选 - 商业/非商业：非商业

1. 提交。你会得到一个 客户端ID 在下一页。复制它。

将您的客户ID保密。 不要将其提交给git或公开分享。

安装

# Clone or download this repo
cd mal-mcp-server

# Install dependencies
npm install

# Build
npm run build

配置

服务器需要一个环境变量：

MAL_CLIENT_ID=your_client_id_here

您可以在MCP客户端配置（见下文）、shell配置文件或 .env 文件（如果添加 dotenv 支持自己）。

与Claude Desktop一起使用

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mal": {
      "command": "node",
      "args": ["/absolute/path/to/mal-mcp-server/dist/index.js"],
      "env": {
        "MAL_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

编辑后重新启动Claude Desktop。

使用Claude代码

从项目目录中添加：

claude mcp add mal -- node /absolute/path/to/mal-mcp-server/dist/index.js

然后在运行Claude Code之前在shell中设置环境变量，或将其添加到命令中：

MAL_CLIENT_ID=your_client_id_here claude

或者，添加到您的Claude Code MCP配置中(~/.claude/claude_code_config.json 或项目级别 .mcp.json):

{
  "mcpServers": {
    "mal": {
      "command": "node",
      "args": ["/absolute/path/to/mal-mcp-server/dist/index.js"],
      "env": {
        "MAL_CLIENT_ID": "your_client_id_here"
      }
    }
  }
}

查询示例

一旦连接，你可以问你的AI一些事情，比如：

• *“在MAL中搜索关于可爱猫的动漫”*
• *“现在收视率最高的动漫是什么？”*
• *“按分数排序显示本季播出的内容”*
• *“给我Frieren（动漫ID 154587）的详细信息”*
• *“评价最高的漫画是什么？”*
• *“在MAL上查找漫画《狂暴》”*
• *“2024年夏天播出了什么动漫？”*
• *“给我看本季得分高于7的动作动漫”*
• *“最受欢迎的浪漫喜剧动漫是什么？”* （使用genre_mode：“and”）
• *“今年冬天首映了什么新动漫？”* （仅使用current_season\_）

人工智能将调用适当的工具并显示结果。

工具详细信息

共享筛选器参数

5列表返回工具(mal_search_anime, mal_anime_ranking, mal_anime_seasonal, mal_search_manga, mal_manga_ranking)all支持服务器端过滤，当任何一个过滤器处于活动状态时，服务器从MAL API获取一个500项的页面，在客户端进行过滤，并返回匹配结果。一个工具调用=一个API调用。机器人通过传递来控制扫描深度 offset 在随后的通话中。

常用过滤器（所有列表工具）：

• genres_include （string\[\]）：仅包含具有匹配类型的项目（不区分大小写）。看 genre_mode.
• genres_exclude （string\[\]）：排除这些类型中的任何一个项目（不区分大小写）
• genre_mode （“或”|“和”）：如何 genres_include matches--“or”=任何流派匹配（默认），“and”=所有流派都必须存在
• min_score （数字）：最低平均分，0-10
• min_members （数量）：最低MAL列表成员

仅动漫滤镜：

• media_type （字符串\[\]）： "tv", "ova", "movie", "ona", "special", "music"
• status （字符串）： "currently_airing", "finished_airing", "not_yet_aired"
• source （字符串\[\]）： "manga", "light_novel", "original", "visual_novel", "game", "other"

季节性过滤器：

• current_season_only （boolean）：仅显示其动画 start_season 匹配查询的季节（过滤掉像长跑运动员这样的连续节目）

仅漫画过滤器：

• media_type （字符串\[\]）： "manga", "novel", "one_shot", "doujinshi", "manhwa", "manhua", "oel"
• status （字符串）： "currently_publishing", "finished", "not_yet_published"

当过滤器处于活动状态时，输出包括摘要和上下文感知提示：

Found 8 results out of 500 scanned, showing 5 | Filters: genres(AND)=Action,Romance, min_score>=7.5
More matches found in scanned items. Use offset=234 to continue, or increase limit to see more from this scan.

如果在扫描区域中未找到匹配项，但存在更多API数据：

Found 0 results out of 500 scanned, showing 0 | Filters: min_score>=9.0
No matches in scanned items. More data available to scan — use offset=500 to search the next section, or try adjusting your filters.

mal_search_anime

按关键字搜索。返回标题、配乐、状态、类型、剧集、流派、工作室、季节和MAL链接。

参数：

• query （字符串，必填）：搜索文本，2-200个字符
• limit （数字）：1-100，默认10
• offset （number）：分页，默认为0
• nsfw （boolean）：包含NSFW结果，默认为false
• 加 共享筛选器 和动漫专用过滤器

mal_get_anime_details

通过MAL动漫ID获取详细信息。返回所有内容 search does plus：简介、背景、替代标题、播出日期、广播信息、评级、相关动漫、推荐和列表统计。

参数：

• anime_id （数字，必填）：MAL动漫ID

mal_anime_ranking

排名列表。过滤后的结果保持其原始的MAL排名。

可用的排名类型：

• all --整体顶级动漫
• airing --当前正在播放的顶部
• upcoming --即将上市
• tv --顶级电视剧
• ova — 顶级 OVA
• movie --热门电影
• special --顶级特价
• bypopularity --大多数成员
• favorite --最受欢迎

参数：

• ranking_type （string）：默认为“all”
• limit （数字）：1-100，默认10
• offset （数字）：默认值0
• 加 共享筛选器 和动漫专用过滤器

mal_anime_季节性

按季节浏览动漫。如果省略年份/季节，则默认为当前季节。

参数：

• year （数量）：1900-2100，可选
• season （string）：“冬天”|“春天”|“夏天”|“秋天”，可选
• sort （字符串）：“anime_score”|“anime_num_list_users”|“”，默认值“”
• limit （数字）：1-100，默认10
• offset （数字）：默认值0
• 加 共享筛选器，仅动漫滤镜，以及 current_season_only

mal_search_manga

喜欢动漫搜索，但喜欢漫画。返回标题、分数、类型、卷数、章节、流派、作者。

参数：

• query （字符串，必填）：2-200个字符
• limit （数字）：1-100，默认10
• offset （数字）：默认值0
• nsfw （boolean）：默认值为false
• 加 共享筛选器 和仅限漫画的过滤器

mal_get-manga_details

完整的漫画细节由MAL ID提供。概要、作者、连载、相关作品、推荐。

参数：

• manga_id （数字，必填）：MAL漫画ID

mal_manga_ranking

排名漫画列表。过滤后的结果保持其原始的MAL排名。

可用类型： all, manga, novels, oneshots, doujin, manhwa, manhua, bypopularity, favorite.

参数：

• ranking_type （string）：默认为“all”
• limit （数字）：1-100，默认10
• offset （数字）：默认值0
• 加 共享筛选器 和仅限漫画的过滤器

建筑

src/
├── index.ts     # MCP server setup + all 7 tool registrations
├── client.ts    # MAL API client (typed fetch wrapper)
├── filters.ts   # Filter schemas, predicates, and filtered-fetch orchestrator
├── format.ts    # Response formatting (API data → readable text)
└── types.ts     # TypeScript interfaces for MAL API responses

• 运输：stdio（作为MCP客户端的子进程运行）
• 认证：用途 X-MAL-CLIENT-ID header（只读访问不需要OAuth）
• 没有外部HTTP库 --使用Node.js原生 fetch
• 零运行时依赖关系 超越MCP SDK和Zod

未来工作（第二阶段）

这些功能需要OAuth 2.0身份验证（PKCE流）：

• mal_get_my_animelist --查看您的动漫列表
• mal_update_anime_status --添加/更新列表中的条目
• mal_anime_suggestions --MAL的个性化建议
• mal_get_my_mangalist --查看您的漫画列表
• mal_update_manga_status --添加/更新漫画条目
• mal_get_user_info --获取您的个人资料信息

MAL API使用带PKCE的OAuth 2.0。总体流程如下：

1. 生成PKCE代码_验证器+代码_挑战
2. 打开浏览器，访问MAL的身份验证URL
3. 用户授权→ 回调函数接收身份验证码
4. 访问令牌+刷新令牌的交换代码
5. 存储令牌并在过期时自动刷新

API协议

通过使用MAL API，您同意 API许可和开发协议.要点：

• 保密您的客户ID
• 不要抓取-只通过API访问数据
• 非商业个人使用是可以的
• 不在服务器端存储MAL用户个人信息
• 不要模仿MAL体验

许可证

麻省理工学院