myanimelist-mcp

An MCP server that exposes your MyAnimeList data — watch list, scores, progress, rankings, recommendations — as tools, plus a premium MCP Apps UI that renders those results as an interactive, anime-styled interface right inside the chat. Any assistant that speaks MCP can analyze your taste, browse seasons, and edit your list; on hosts that support MCP Apps it does so through the UI below.

Python 3.12 · FastMCP 3 (stdio) · React + Vite for the UI.

Installation

Requires uv. No clone, no build, no Docker.

uvx myanimelist-mcp

The server speaks MCP over stdio: it prints nothing and waits on stdin for JSON-RPC, so running it by hand looks like a hang — that is correct behaviour. Your MCP client is what launches it. Add it to your client config — macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "myanimelist": {
      "command": "uvx",
      "args": ["myanimelist-mcp"],
      "env": {
        "MAL_CLIENT_ID": "your-client-id",
        "MAL_CLIENT_SECRET": "your-client-secret",
        "MAL_REFRESH_TOKEN": "your-refresh-token",
        "MAL_TIMEZONE": "Europe/Istanbul"
      }
    }
  }
}

Then quit and reopen the client completely. See Authentication for how to get those credentials.

spawn uvx ENOENT? Desktop clients launch servers with a minimal PATH that usually excludes ~/.local/bin. Run which uvx and put the absolute path in "command".

Your credentials live in that file in plaintext, and stderr from this server is persisted by some clients (e.g. ~/Library/Logs/Claude/). Consider chmod 600 on the config, and revoke the MAL token if you ever share logs.

For Claude Code:

claude mcp add --env MAL_CLIENT_ID=… --env MAL_REFRESH_TOKEN=… \
  --transport stdio myanimelist -- uvx myanimelist-mcp

Pinning a version, or installing with pip instead:

uvx --from 'myanimelist-mcp==X.Y.Z' myanimelist-mcp
pip install myanimelist-mcp   # then "command": "myanimelist-mcp"
                              # or   "command": "python", "args": ["-m", "mal_mcp"]

The interface

Each read tool ships a ui:// app resource alongside its text summary, so hosts that support MCP Apps render the result as a live view. The model still receives the compact text summary; the full data travels to the iframe as structured content. Where the host has no MCP Apps support, the tools degrade to those text summaries and everything still works.

The detail and list views edit your MAL entries in place (status / score / progress) and navigate between titles — all through the same tools, so nothing UI-only happens behind the model's back. The theme follows the host's light/dark mode; cover art loads from MAL's CDN.

Tools

Anime

Manga

Discovery

Users

Write tools — these modify your MAL list

Aggregate tools (get_user_stats, analyze_taste) fetch the entire list in one paginated pass (safety cap: 20,000 entries — beyond that a truncated/WARNING marker is included). paging.next URLs are validated (https + api.myanimelist.net) before being followed, so the bearer token can never be sent elsewhere. Verified MAL API facts (fields syntax, pagination, limits, error shapes) are documented in NOTES.md.

Development

uv sync                 # install Python dependencies
uv run pytest           # unit tests (pure helpers, no network)
uv run myanimelist-mcp  # run the server over stdio (waits on stdin for JSON-RPC)

Building the UI

The server runs without the UI bundle (it serves a small placeholder), so a clone never needs Node. To build the real interface:

cd ui
npm ci
npm run build   # emits src/mal_mcp/ui/dist/index.html (a single self-contained file)

For UI development without a host, npm run dev in ui/ renders every view with fixture data and a view switcher — the screenshots above are those views.

Released wheels always ship a freshly built bundle: .github/workflows/publish.yml builds it before uv build and fails the release if it is missing.

Authentication

The server needs a MyAnimeList access token and stores nothing on disk. Set the credentials in the "env" block of your MCP client config, in one of two ways (this is the precedence order):

1. MAL_REFRESH_TOKEN (+ MAL_CLIENT_ID, MAL_CLIENT_SECRET) — recommended. The server mints and renews access tokens itself via the OAuth refresh_token grant, in memory only. Set up once, no monthly re-pasting.
2. MAL_ACCESS_TOKEN — a static token (expires ~31 days); simplest for a quick test.

Getting a MAL token

1. Create an API app at https://myanimelist.net/apiconfig → Create ID, App Type: Web (this is what makes MAL issue a Client Secret). Set the redirect URL to your OAuth callback, or a localhost URL like http://localhost:8080/callback for the manual flow.
2. MAL uses plain PKCE only (no S256), so the code verifier and challenge are the same string. Obtain a token once:

# 1) code verifier (43-128 chars); challenge == verifier for plain PKCE
VERIFIER=$(python3 -c "import secrets; print(secrets.token_urlsafe(64)[:100])")

# 2) open in a browser, log in, approve — you get ?code=<CODE> at your redirect URL:
#    https://myanimelist.net/v1/oauth2/authorize?response_type=code&client_id=<CLIENT_ID>&code_challenge=$VERIFIER&code_challenge_method=plain&state=x&redirect_uri=<URL_ENCODED_REDIRECT_URL>

# 3) exchange the code for tokens:
curl -s https://myanimelist.net/v1/oauth2/token \
  -d client_id=<CLIENT_ID> -d client_secret=<CLIENT_SECRET> \
  -d grant_type=authorization_code -d code=<CODE> \
  -d code_verifier=$VERIFIER -d redirect_uri=<REDIRECT_URL>
# → {"token_type":"Bearer","expires_in":2678400,"access_token":"...","refresh_token":"..."}

Keep the refresh_token for MAL_REFRESH_TOKEN (option 1), or the access_token for MAL_ACCESS_TOKEN (option 2).

Environment variables

Project layout

src/mal_mcp/
├── server.py       # FastMCP app, token helper, 20 tools, stats/format/summary helpers
├── mal_client.py   # MAL API wrapper: fields, pagination (paging.next), retries, error mapping
├── token_manager.py# self-renewing OAuth refresh_token grant (in-memory)
├── __main__.py     # `python -m mal_mcp`
└── ui/             # MCP Apps layer: ui:// resource + meta/ToolResult helpers
    └── dist/       # built single-file HTML bundle (gitignored; built by CI for releases)
ui/                 # Vite + React + TypeScript app (motion animations, 6 views)
tests/              # offline unit tests (pure helpers, token manager, UI contract)
NOTES.md            # verified MAL API / FastMCP facts

The PyPI distribution is myanimelist-mcp; the import package is mal_mcp.

License

MIT