mal-mcp

An MCP 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 (unofficial MAL API). Search, details, rankings, seasons, characters, recommendations, reviews and public profiles. No credentials required.

• Your personal list → official MyAnimeList API. Read, update and delete entries on your own anime/manga list. Requires a user token (see docs/auth.md).

If no token is configured, the personal-list tools return a clear, actionable error and everything else keeps working.

Related MCP server: mangadex-mcp

Tools

Prompts: recommend_similar, seasonal_overview.

Install

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

Download mal-mcp.mcpb from the latest release and open it with your MCP client. The client will prompt for the optional token fields.

From source

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:

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

Or with the Claude Code CLI:

claude mcp add mal \
  -e MAL_CLIENT_ID=... -e MAL_CLIENT_SECRET=... -e MAL_REFRESH_TOKEN=... \
  -- 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 a token is configured. The server does not read a .env file, so pass credentials via this env block (or your shell environment). See docs/auth.md for obtaining the token values and docs/clients.md for more clients.

Configuration

All configuration is via environment variables, all optional — without credentials the read tools still work. For the personal-list tools, set the three credentials below; the access token is then fetched and refreshed automatically.

Provide these in your MCP client config's env block (the server does not read a .env file). See docs/auth.md for how to obtain the credentials, and docs/clients.md for client configuration snippets.

NSFW content

NSFW (adult) results are not filtered by default — the server returns whatever the upstream API provides. Search tools accept an optional sfw parameter; set sfw: true to exclude adult entries via Jikan.

Development

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

Runtime requires Node ≥ 18 (global fetch). See AGENTS.md for contributor/agent guidance.

Updating

To be notified of new versions, click Watch → Releases on GitHub.

• .mcpb bundle: download the new mal-mcp.mcpb from the releases page and reinstall it in your client (it replaces the old version).

• From source: git pull && npm ci && npm run build.

• npx (after npm publish): unpinned npx -y mal-mcp fetches the latest on the next run; if you pinned a version, bump it.

See the CHANGELOG for what changed in each release.

Attribution and terms

This is an unofficial project and is not affiliated with or endorsed by MyAnimeList. Read data is provided by Jikan, an unofficial MAL API; please respect its rate limits. Personal-list operations use the official MyAnimeList API under your own account and token. Use is subject to the MyAnimeList Terms of Service.

License

MIT © Grinv