mal-mcp

# MAL MCP Server

[![npm version](https://img.shields.io/npm/v/mal-mcp.svg)](https://www.npmjs.com/package/mal-mcp)
[![CI](https://github.com/Grinv/mal-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Grinv/mal-mcp/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/npm/l/mal-mcp.svg)](LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.Grinv%2Fmal--mcp-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Grinv/mal-mcp&version=latest)
[![mal-mcp MCP server](https://glama.ai/mcp/servers/Grinv/mal-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Grinv/mal-mcp)

An [MCP](https://modelcontextprotocol.io) server for **MyAnimeList**. It works with
any MCP-compatible client or agent (Claude Desktop/Code, Cursor, VS Code, Cline,
Continue, and others) — the server speaks the standard MCP stdio protocol.

## What it does

It uses a hybrid backend:

- **Reads → [Jikan](https://jikan.moe) (unofficial MAL API).** Search, details,
  rankings, seasons, characters, recommendations, reviews and public profiles.
  No credentials required.
- **Your personal list → official [MyAnimeList API](https://myanimelist.net/apiconfig/references/api/v2).**
  Read, update and delete entries on your own anime/manga list. Requires a
  one-time login (see below).

## What you need (and what it gets you)

Nothing is required to get started — you can skip straight to
[Install](#install). Everything below is optional, and each step just adds
more:

| You set...                                                                                                                                            | You get...                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| _(nothing)_                                                                                                                                           | Search, details, rankings, seasons, characters, reviews, public profiles, and more — works immediately, no signup.                                                                |
| A MyAnimeList **Client ID** ([2 minutes, free →](#connect-your-myanimelist-account-for-the-personal-list-tools))                                      | Same as above, plus: 11 read tools (search, rankings, seasons, recommendations, details, statistics) keep working smoothly even during a MyAnimeList hiccup. Still no login step. |
| The Client ID above, **plus** running the `login_mal` tool once ([same walkthrough →](#connect-your-myanimelist-account-for-the-personal-list-tools)) | Everything above, plus your **own MyAnimeList list**: view it, add/update entries, mark things watched, remove entries.                                                           |

Without a login, the personal-list tools reply with a clear message telling
you how to get one — everything else keeps working regardless.

## Example queries

Once it's connected, just ask your agent in natural language.

**No credentials needed** (search, details, rankings, seasons, characters, …):

```
"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?"
"Show the public profile and favorites of user Xinil."
"Pick a random highly-rated anime for me."
```

**With your MyAnimeList account** (after a one-time `login_mal`; see
[Connect your MyAnimeList account](#connect-your-myanimelist-account-for-the-personal-list-tools)):

```
"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."
```

## Tools

| Tool                                                                                  | Backend | Auth  |
| ------------------------------------------------------------------------------------- | ------- | ----- |
| `search_anime`, `search_manga`                                                        | Jikan   | none  |
| `get_anime`, `get_manga`                                                              | Jikan   | none  |
| `get_anime_characters`, `get_anime_recommendations`, `get_anime_reviews`              | Jikan   | none  |
| `get_manga_characters`, `get_manga_recommendations`, `get_manga_reviews`              | Jikan   | none  |
| `get_anime_episodes`                                                                  | Jikan   | none  |
| `get_anime_genres`, `get_manga_genres`                                                | Jikan   | none  |
| `search_characters`, `get_character`                                                  | Jikan   | none  |
| `search_people`, `get_person`, `get_anime_staff`                                      | Jikan   | none  |
| `get_anime_statistics`, `get_manga_statistics`                                        | Jikan   | none  |
| `get_random_anime`, `get_random_manga`, `get_random_character`, `get_random_person`   | Jikan   | none  |
| `get_anime_news`                                                                      | Jikan   | none  |
| `get_top_anime`, `get_top_manga`                                                      | Jikan   | none  |
| `get_top_people`, `get_top_characters`                                                | Jikan   | none  |
| `get_seasonal_anime`, `get_upcoming_season`, `get_seasons_list`, `get_anime_schedule` | Jikan   | none  |
| `get_producers`                                                                       | Jikan   | none  |
| `get_user_profile`, `get_user_favorites`                                              | Jikan   | none  |
| `get_my_user_info`, `get_my_anime_list`, `get_my_manga_list`                          | MAL     | token |
| `update_my_anime_status`, `update_my_manga_status`                                    | MAL     | token |
| `delete_my_anime_list_item`, `delete_my_manga_list_item`                              | MAL     | token |
| `login_mal`, `submit_mal_redirect`                                                    | MAL     | login |

`token` = needs a MyAnimeList login (run `login_mal` once). Prompts:
`recommend_similar`, `seasonal_overview`, `hidden_gems`. `recommend_similar`'s
title is optional — omit it and it'll ask which anime you mean; clients that
support prompt-argument completion get live title suggestions as you type.

## Install

### As an `.mcpb` bundle (one-click, e.g. Claude Desktop)

Download [**`mal-mcp.mcpb`**](https://github.com/Grinv/mal-mcp/releases/latest/download/mal-mcp.mcpb)
(always the latest release) and open it with your MCP client. It prompts for an optional
MyAnimeList **Client ID** — set it and run the `login_mal` tool to enable the personal-list
tools (see [Connect your MyAnimeList account](#connect-your-myanimelist-account-for-the-personal-list-tools)).
Leave it blank to use just the credential-free read tools.

### From source

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

This produces a self-contained `dist/index.js`. Point your client at it (see below).

## Connect it to an MCP client

Add the server to your client's MCP config (Claude Desktop/Code, Cursor, VS Code,
Cline, …). The simplest option is `npx` — no clone, no build:

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

Or with the Claude Code CLI:

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

If you built from source instead, replace `"command": "npx", "args": ["-y", "mal-mcp"]`
with `"command": "node", "args": ["/absolute/path/to/mal-mcp/dist/index.js"]`.

The `env` block is **optional** — omit it to use only the credential-free read
tools (search, details, rankings, …); the personal-list tools will return a clear
error until you log in. To enable them, set `MAL_CLIENT_ID` and run the
**`login_mal`** tool once (a one-time browser authorization; the token is then
stored and refreshed automatically). The server does not read a `.env` file, so
pass config via this `env` block (or your shell environment). See
[docs/auth.md](docs/auth.md) for the full login walkthrough and
[docs/clients.md](docs/clients.md) for more clients.

## Connect your MyAnimeList account (for the personal-list tools)

The search/browse tools work with **no setup**. To use the personal-list tools
(`get_my_*`, `update_my_*`, `delete_my_*`), authorize your account once. It takes
about two minutes. There is **no client secret** — mal-mcp uses the modern
public-client flow (PKCE), so you only need a Client ID.

**Step 1 — Register a MyAnimeList app (one minute).**

1. Go to <https://myanimelist.net/apiconfig> and click **Create ID**.
2. **App Type:** choose **`other`**. _(Not `web` — that type forces a client
   secret this server doesn't use.)_
3. **App Redirect URL:** enter exactly
   ```
   http://localhost:8080/callback
   ```
   _(If port 8080 is already used on your machine, pick another port here and set
   `MAL_OAUTH_PORT` to the same number — see [Configuration](#configuration).)_
4. Fill the remaining required fields with anything