内容
# mal-mcp
一款适用于 **MyAnimeList** 的 [MCP](https://modelcontextprotocol.io) 服务器。它与任何MCP兼容的客户端或代理（Claude Desktop/Code、Cursor、VS Code、Cline、Continue等）配合使用——服务器采用标准的MCP stdio协议。
## 功能
它使用混合后端：
- **读取 → [Jikan](https://jikan.moe)（非官方MAL API）**。搜索、详情、排名、季度、角色、推荐、评论和公开个人资料。不需要凭证。
- **您的个人列表 → 官方 [MyAnimeList API](https://myanimelist.net/apiconfig/references/api/v2)**。读取、更新和删除您自己的动漫/漫画列表条目。需要用户令牌（参见 [docs/auth.md](docs/auth.md)）。
如果未配置令牌，个人列表工具将返回清晰、可操作的错误，其他一切保持正常运行。
## 工具
| 工具 | 后端 | 认证 |
| ------------------------------------------------------------------------------------- | ------ | ----- |
| `search_anime`, `search_manga` | Jikan | 无 |
| `get_anime`, `get_manga` | Jikan | 无 |
| `get_anime_characters`, `get_anime_recommendations`, `get_anime_reviews` | Jikan | 无 |
| `get_manga_characters`, `get_manga_recommendations`, `get_manga_reviews` | Jikan | 无 |
| `get_anime_episodes` | Jikan | 无 |
| `get_anime_genres`, `get_manga_genres` | Jikan | 无 |
| `search_characters`, `get_character` | Jikan | 无 |
| `search_people`, `get_person`, `get_anime_staff` | Jikan | 无 |
| `get_anime_statistics`, `get_manga_statistics` | Jikan | 无 |
| `get_random_anime`, `get_random_manga`, `get_random_character`, `get_random_person` | Jikan | 无 |
| `get_anime_news` | Jikan | 无 |
| `get_top_anime`, `get_top_manga` | Jikan | 无 |
| `get_top_people`, `get_top_characters` | Jikan | 无 |
| `get_seasonal_anime`, `get_upcoming_season`, `get_seasons_list`, `get_anime_schedule` | Jikan | 无 |
| `get_producers` | Jikan | 无 |
| `get_user_profile`, `get_user_favorites` | Jikan | 无 |
| `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 | 令牌 |
提示：`recommend_similar`, `seasonal_overview`.
## 安装
### 作为 `.mcpb` 包（一键安装，例如 Claude Desktop）
从 [最新版本](https://github.com/Grinv/mal-mcp/releases) 下载 `mal-mcp.mcpb` 并用您的MCP客户端打开。客户端将提示可选的令牌字段。
### 从源代码
```sh
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` ——无需克隆，无需构建：
```json
{
"mcpServers": {
"mal": {
"command": "npx",
"args": ["-y", "mal-mcp"],
"env": {
"MAL_CLIENT_ID": "...",
"MAL_CLIENT_SECRET": "...",
"MAL_REFRESH_TOKEN": "..."
}
}
}
}
```
或使用Claude Code CLI：
```sh
claude mcp add mal \
-e MAL_CLIENT_ID=... -e MAL_CLIENT_SECRET=... -e MAL_REFRESH_TOKEN=... \
-- npx -y mal-mcp
```
如果您是从源代码构建的，请将 `"command": "npx", "args": ["-y", "mal-mcp"]` 替换为 `"command": "node", "args": ["/absolute/path/to/mal-mcp/dist/index.js"]`。
`env` 块是 **可选的** ——省略它以仅使用无凭证的读取工具（搜索、详情、排名等）；个人列表工具将返回清晰的错误，直到配置令牌。服务器不读取 `.env` 文件，因此请通过此 `env` 块（或您的 shell 环境）传递凭证。有关获取令牌值的信息，请参见 [docs/auth.md](docs/auth.md)，有关更多客户端，请参见 [docs/clients.md](docs/clients.md)。
## 配置
所有配置均通过环境变量完成，所有变量均为可选 —— 无凭证时，读取工具仍可正常工作。对于个人列表工具，请设置以下 **三个凭证**；然后自动获取和刷新访问令牌。
| 变量 | 目的 |
| --------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `MAL_CLIENT_ID`, `MAL_CLIENT_SECRET`, `MAL_REFRESH_TOKEN` | 个人列表凭证（自动刷新）。参见 [docs/auth.md](docs/auth.md)。 |
| `MAL_ACCESS_TOKEN` | _高级/可选。_ 独立令牌；有效期约30天，无需刷新。 |
| `MAL_TOKEN_STORE` | 覆盖令牌缓存路径（默认：操作系统配置目录）。 |
| `LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` \| `silent` （默认 `info`）。 |
### 调整（很少需要）
这些变量具有合理的默认值；仅在您自行托管Jikan或需要不同计时时才更改。
| 变量 | 目的 |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JIKAN_MIN_INTERVAL_MS` | Jikan调用之间的最小间隔（默认 `400`）。在此基础上，客户端强制执行Jikan发布的3/s **和** 60/min限制；设置为 `0` 以禁用所有客户端限流。 |
| `CACHE_TTL_MS` | 内存读取缓存的TTL（默认 `300000` = 5分钟）。 |
| `HTTP_TIMEOUT_MS`, `HTTP_RETRIES` | 每个请求的超时时间（默认 `15000`）和暂时失败的重试次数（默认 `2`）。 |
| `JIKAN_BASE_URL`, `MAL_BASE_URL`, `MAL_OAUTH_BASE_URL` | 覆盖上游基准URL（例如，自托管的Jikan实例）。 |
在MCP客户端配置的`env`块中提供这些变量（服务器 **不** 读取`.env`文件）。有关获取凭证的信息，请参见 [docs/auth.md](docs/auth.md)，有关客户端配置代码段，请参见 [docs/clients.md](docs/clients.md)。
## NSFW内容
NSFW（成人）结果 **不** 默认过滤 —— 服务器返回上游API提供的任何内容。搜索工具接受一个可选的`sfw`参数；设置`sfw: true`以通过Jikan排除成人条目。
## 开发
```sh
npm run build # 类型检查 + 打包到 dist/
npm test # node:test 套件（模拟，离线）
npm run test:coverage
npm run lint
npm run format
npm run check:api # 上游端点的实时健康检查
npm run inspector # 在 MCP Inspector 下运行
```
运行时需要 Node ≥ 18（全局 `fetch`）。有关贡献者/代理的指南，请参见 [AGENTS.md](AGENTS.md)。
## 更新
要接收新版本的通知，请在GitHub上点击 **Watch → Releases**。
- **`.mcpb` 包：** 从 [发布页面](https://github.com/Grinv/mal-mcp/releases) 下载新的 `mal-mcp.mcpb` 并在您的客户端中重新安装（它将替换旧版本）。
- **从源代码：** `git pull && npm ci && npm run build`。
- **npx（npm发布后）：** 未固定的 `npx -y mal-mcp` 在下一次运行时获取最新版本；如果您固定了版本，请升级。
有关每个版本更改的内容，请参见 [CHANGELOG](CHANGELOG.md)。
## 归属和条款
这是一个 **非官方** 项目，与MyAnimeList无关，也未得到MyAnimeList的认可。读取数据由 [Jikan](https://jikan.moe) 提供，这是一个非官方的MAL API；请尊重其速率限制。个人列表操作使用您自己的帐户和令牌在官方 [MyAnimeList API](https://myanimelist.net/apiconfig/references/api/v2) 下进行。使用须遵守 [MyAnimeList 服务条款](https://myanimelist.net/about/terms_of_use)。
## 许可证
[MIT](LICENSE) © Grinv
