MyAnimeList MCP Server

Search, inspect, rank, and manage MyAnimeList anime and manga from any MCP-compatible AI client.

MyAnimeList MCP Server is a Python MCP server for the MyAnimeList API. It uses MCP SDK v2, keeps stdio as the default transport, and exposes the MAL API through typed tools that work with Claude, Codex, Gemini, and other MCP clients.

Features

• 15 tools for anime, manga, rankings, seasonal releases, public lists, and the authenticated user profile.

• MCP SDK v2 with stdio transport and protocol compatibility for existing clients.

• One reusable async HTTP client per server lifespan.

• Explicit timeouts, bounded retries for safe GET requests, connection limits, and sanitized errors.

• MAL OAuth with PKCE plain mode, state validation, localhost callback handling, token reuse, and concurrency locking.

• Memory-only access and refresh tokens; no token persistence files.

• Docker image built from the locked dependency graph with uv.

Related MCP server: mal-mcp

How it works

The server starts an MCP stdio process. Each tool call is translated into a MyAnimeList API request through the shared client. Public requests use the MAL client ID; authenticated requests add a bearer token obtained from the in-memory OAuth manager.

Successful responses preserve the MAL response shape. Error responses use a stable error field and, when available, status_code, without returning raw response bodies, URLs, authorization codes, or tokens.

Prerequisites

• Python 3.12 or newer

• uv

• A MyAnimeList API client ID

• A MyAnimeList client secret for authenticated tools

• Docker, only if you want to run the container image

Quick start

Clone the repository and install the locked environment:

git clone https://github.com/MorpKnight/myanimelist-mcp.git
cd myanimelist-mcp
cp .env.example .env
uv sync --locked

Edit .env and set at least MAL_CLIENT_ID. Add MAL_CLIENT_SECRET before using authenticated tools.

Run the server:

uv run --locked main.py

The default transport is stdio. stdout is reserved for MCP messages; OAuth diagnostics are sent to stderr.

MyAnimeList application setup

Create an application from MyAnimeList API Config.

Use these values as a starting point:

• App Description: An open-source MCP server for searching and managing MyAnimeList data from AI clients.

• App Redirect URL: http://127.0.0.1:8080/callback

• Homepage URL: https://github.com/MorpKnight/myanimelist-mcp

Copy the generated client ID and client secret into .env. The redirect URL must exactly match the URL registered in MAL.

Configure an MCP client

Claude Desktop

Add this entry to claude_desktop_config.json and replace the project path:

{
  "mcpServers": {
    "myanimelist": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/myanimelist-mcp",
        "run",
        "--locked",
        "main.py"
      ]
    }
  }
}

Keep .env in the project directory so the server can load it when started with --directory.

Codex and other stdio clients

Use the same command in the client's MCP server configuration:

uv --directory /absolute/path/to/myanimelist-mcp run --locked main.py

MCP clients can use different configuration wrappers, but discovery, schemas, and tool calls use the same MCP protocol.

Smithery

The repository includes a stdio smithery.yaml manifest. The manifest can be published under the project's own Smithery namespace when that namespace is available. No upstream Smithery namespace is assumed by this repository.

Docker

Build the image:

docker build -t myanimelist-mcp .

Run it as an MCP stdio server:

docker run --rm -i --env-file .env myanimelist-mcp

The image installs dependencies with uv sync --locked and does not include .env, tests, Git metadata, or local caches.

Configuration

Headless OAuth

For a deployment without a browser, set a valid refresh token and disable interactive browser opening:

MAL_REFRESH_TOKEN=your_refresh_token
MAL_OPEN_BROWSER=false

Refresh tokens are never written back to disk by this server.

Available tools

Anime

Manga

User

Development and testing

Install all locked dependencies, including the development group:

uv sync --locked

Run linting and tests:

uv run --locked ruff check .
uv run --locked pytest -q

The default suite uses mocked HTTP responses, MCP in-memory tests, OAuth callback tests, and stdio subprocess tests. It does not mutate a real MAL account.

Troubleshooting

MAL_CLIENT_ID is not configured

Set MAL_CLIENT_ID in .env or in the MCP client's process environment, then restart the client.

OAuth callback port conflict

Stop the process using port 8080, or choose another loopback port and register the matching redirect URL in MAL:

MAL_CALLBACK_PORT=18080

OAuth does not open a browser

Use MAL_OPEN_BROWSER=true for interactive authorization. For headless use, provide MAL_REFRESH_TOKEN and set MAL_OPEN_BROWSER=false.

MCP client reports malformed output

Start the server with the stdio command above. Do not add application prints to stdout; stdout must contain only MCP protocol messages.

Authenticated tool returns an OAuth error

Check the client ID, client secret, refresh token, redirect URL, and callback port. If the refresh token is expired or revoked, run the interactive flow again.

Resources

• MCP Python SDK

• MCP documentation

• MyAnimeList authorization reference

• MyAnimeList API v2 reference

• MyAnimeList API Config

Project policies and attribution are documented in CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, and NOTICE.md.