<div align="center">

MyAnimeList MCP Server

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

<p> <a href="https://github.com/MorpKnight/myanimelist-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/MorpKnight/myanimelist-mcp/ci.yml?label=CI&logo=github" alt="CI status"></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white" alt="Python 3.12+"></a> <a href="https://github.com/modelcontextprotocol/python-sdk"><img src="https://img.shields.io/badge/MCP-SDK%20v2-6B4FBB" alt="MCP SDK v2"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a> </p>

</div>

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.

[!TIP] Public tools work with a MAL client ID. Authenticated tools use OAuth and can either open a local browser flow or use a refresh token in headless environments.

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.

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 <code>error</code> field and, when available, <code>status_code</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 <code>.env</code> and set at least <code>MAL_CLIENT_ID</code>. Add <code>MAL_CLIENT_SECRET</code> 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: <code>An open-source MCP server for searching and managing MyAnimeList data from AI clients.</code>
• App Redirect URL: <code>http://127.0.0.1:8080/callback</code>
• Homepage URL: <code>https://github.com/MorpKnight/myanimelist-mcp</code>

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

Configure an MCP client

Claude Desktop

Add this entry to <code>claude_desktop_config.json</code> and replace the project path:

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

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

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 <code>smithery.yaml</code> 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 <code>uv sync --locked</code> and does not include <code>.env</code>, tests, Git metadata, or local caches.

Configuration

Variable	Required	Default	Description
<code>MAL_CLIENT_ID</code>	Yes	—	MyAnimeList API client ID.
<code>MAL_CLIENT_SECRET</code>	OAuth	—	MyAnimeList OAuth client secret.
<code>MAL_REFRESH_TOKEN</code>	No	—	Refresh token for headless authenticated deployments.
<code>MAL_API_URL</code>	No	<code>https://api.myanimelist.net/v2</code>	MAL API base URL.
<code>MAL_OPEN_BROWSER</code>	No	<code>true</code>	Open the browser for interactive OAuth.
<code>MAL_CALLBACK_HOST</code>	No	<code>127.0.0.1</code>	Loopback host for the OAuth callback.
<code>MAL_CALLBACK_PORT</code>	No	<code>8080</code>	Local OAuth callback port.
<code>MAL_CALLBACK_TIMEOUT</code>	No	<code>300</code>	OAuth callback timeout in seconds.

[!IMPORTANT] Keep <code>.env</code> private. Access tokens and refresh tokens are held in memory only, but the values in <code>.env</code> still grant access to your MAL application or account.

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

Tool	Auth	Purpose
<code>get_anime</code>	Public	Search anime by query.
<code>get_anime_details</code>	Public	Fetch details for an anime ID.
<code>get_anime_ranking</code>	Public	Fetch anime rankings.
<code>get_seasonal_anime</code>	Public	Fetch anime for a season and year.
<code>get_anime_list</code>	Public	Fetch a user's public anime list.
<code>get_suggested_anime</code>	OAuth	Fetch suggestions for the authenticated user.
<code>update_myanimelist</code>	OAuth	Update an anime list entry.
<code>delete_myanimelist_item</code>	OAuth	Delete an anime list entry.

Manga

Tool	Auth	Purpose
<code>get_manga</code>	Public	Search manga by query.
<code>get_manga_details</code>	Public	Fetch details for a manga ID.
<code>get_manga_ranking</code>	Public	Fetch manga rankings.
<code>get_manga_list</code>	Public	Fetch a user's public manga list.
<code>update_mymangalist</code>	OAuth	Update a manga list entry.
<code>delete_mymangalist_item</code>	OAuth	Delete a manga list entry.

User

Tool	Auth	Purpose
<code>get_user_profile</code>	OAuth	Fetch the authenticated user's profile.

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

<code>MAL_CLIENT_ID is not configured</code>

Set <code>MAL_CLIENT_ID</code> in <code>.env</code> 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 <code>MAL_OPEN_BROWSER=true</code> for interactive authorization. For headless use, provide <code>MAL_REFRESH_TOKEN</code> and set <code>MAL_OPEN_BROWSER=false</code>.

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.