mal-mcp

Ein Model Context Protocol-Server, der die MyAnimeList v2 API für Claude und andere MCP-kompatible Clients bereitstellt. Er ist in TypeScript geschrieben, läuft lokal über Bun via stdio oder kann als gehosteter Multi-User-Server auf Cloudflare Workers bereitgestellt werden.

Tools

Einrichtung

• configure — nur stdio — speichert die MyAnimeList client_id (und client_secret, falls ausgestellt) des Benutzers. Muss vor jedem anderen Tool aufgerufen werden. Nicht auf dem Worker registriert; auf dem Worker meldet sich jeder Benutzer über den MCP-OAuth-Flow an, wenn er den Server zu seinem Client hinzufügt.

• authenticate — nur stdio (sinnvoll) — startet den MAL-OAuth-Flow; öffnet einen Browser und wartet auf den lokalen Callback. Auf dem Worker ist dies ein No-Op, das aus Kompatibilitätsgründen beibehalten wurde — die Authentifizierung erfolgt automatisch bei der Verbindung über MCP-OAuth.

• get_auth_status — prüft, ob Anmeldedaten und Benutzertoken verfügbar sind.

Öffentlich (nur Client ID)

• search_anime — Anime nach Titel suchen

• get_anime_details — vollständige Details für eine Anime-ID

• get_anime_ranking — Ranglisten (all, airing, upcoming, tv, ova, movie, special, bypopularity, favorite)

• get_seasonal_anime — Anime nach Jahr + Saison

• search_manga — Manga nach Titel suchen

• get_manga_details — vollständige Details für eine Manga-ID

• get_manga_ranking — Ranglisten (all, manga, novels, oneshots, doujin, manhwa, manhua, bypopularity, favorite)

Benutzerspezifisch (OAuth2-Zugriffstoken erforderlich)

• get_current_user — Profil + Anime-Statistiken für den authentifizierten Benutzer

• get_anime_suggestions — personalisierte Anime-Empfehlungen

• get_user_anime_list — öffentliche Anime-Liste eines beliebigen Benutzers lesen (oder @me)

• update_anime_list_status — Listenstatus, Bewertung, gesehene Episoden usw. hinzufügen/aktualisieren

• delete_anime_list_item — einen Anime aus deiner Liste entfernen

• get_user_manga_list — öffentliche Manga-Liste eines beliebigen Benutzers lesen (oder @me)

• update_manga_list_status — Listenstatus, Bewertung, gelesene Kapitel usw. hinzufügen/aktualisieren

• delete_manga_list_item — einen Manga aus deiner Liste entfernen

Related MCP server: Claude Code MCP

Option 1: Lokal über stdio ausführen

1. Installation

bun install

2. Mit deinem MCP-Client verbinden

Füge dies zu claude_desktop_config.json hinzu (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "mal": {
      "command": "bun",
      "args": ["C:\\BrunoLM\\Projects\\mal-mcp\\src\\index.ts"]
    }
  }
}

Für Claude Code verwende claude mcp add oder füge den entsprechenden Block in .claude/mcp.json ein.

3. Deine MAL-Anmeldedaten konfigurieren

Erstelle einen API-Client unter https://myanimelist.net/apiconfig:

• App Type: other / web

• App Redirect URL: http://localhost:8765/callback

Rufe dann von deinem MCP-Client aus das configure-Tool mit deiner client_id (und client_secret, falls MAL eines ausgestellt hat) auf. Die Anmeldedaten werden in ~/.mal-mcp-config.json gespeichert.

4. (Optional) Für benutzerspezifische Tools autorisieren

Rufe authenticate von deinem MCP-Client aus auf. Ein Browser öffnet sich, du genehmigst die Anfrage, der lokale Server auf Port 8765 fängt den Redirect ab und die Token landen in ~/.mal-mcp-tokens.json. Der Server aktualisiert sie von dort aus automatisch.

Wenn du ein CLI bevorzugst:

$env:MAL_CLIENT_ID = "your-client-id"
# $env:MAL_CLIENT_SECRET = "your-client-secret"   # only if issued
bun run auth

Option 2: Auf Cloudflare Workers hosten (Multi-User, MCP OAuth)

Ein einzelner Worker bedient jeden Benutzer über Standard-MCP-OAuth 2.1 (Dynamic Client Registration). Eine URL für alle: https://mal-mcp.<account>.workers.dev/mcp. Während der Anmeldung gibt jeder Benutzer seine eigene MAL client_id (und client_secret, falls ausgestellt) an; der Status pro Benutzer befindet sich in einem Durable Object, das mit einem Hash dieser Anmeldedaten verschlüsselt ist.

1. Operator-Einrichtung (einmalig)

bun install
bunx wrangler login
bunx wrangler kv namespace create OAUTH_KV

Füge die zurückgegebene Namespace-id in wrangler.jsonc ein (ersetze REPLACE_WITH_KV_ID) und stelle dann bereit:

bun run worker:deploy

Für die lokale Entwicklung:

bunx wrangler kv namespace create OAUTH_KV --preview
bun run worker:dev

2. Jeder Benutzer verbindet sich

1. Erstelle einen MAL-API-Client unter https://myanimelist.net/apiconfig (App Type: other). Setze die App Redirect URL auf:

   https://mal-mcp.<account>.workers.dev/mal/callback

   (Diese exakte URL — dieselbe für jeden Benutzer einer bestimmten Bereitstellung.)

2. Füge den MCP-Server zu deinem Client hinzu:

   claude mcp add --transport http mal https://mal-mcp.<account>.workers.dev/mcp

   Oder äquivalent in der Konfiguration:

   {
     "mcpServers": {
       "mal": {
         "url": "https://mal-mcp.<account>.workers.dev/mcp"
       }
     }
   }

3. Dein MCP-Client öffnet beim ersten Verbinden einen Browser-Tab. Die Autorisierungsseite des Workers fragt nach deiner MAL client_id (und client_secret, falls ausgestellt), leitet dich zur Genehmigung an MyAnimeList weiter und führt dich dann zu deinem MCP-Client zurück — jetzt angemeldet. Zugriffs- und Aktualisierungstoken werden in deinem Durable Object gespeichert; das MAL-Zugriffstoken wird automatisch aktualisiert.

Sicherheitshinweise für gehostete Bereitstellungen

• Der Worker ist sein eigener OAuth 2.1-Autorisierungsserver für MCP. Bearer-Token, die an deinen MCP-Client ausgegeben werden, sind auf dich beschränkt; das Durchsickern eines Tokens ermöglicht es dem Inhaber, in deinem Namen MAL aufzurufen, bis das Token abläuft.

• Unterschiedliche MAL-Anmeldedaten → unterschiedliches Durable Object → vollständig getrennter Status. Es gibt keinen zwischen Benutzern geteilten Status.

• Der Worker speichert keine eigenen MAL-Anmeldedaten; jeder Benutzer stellt seinen eigenen MAL-API-Client bereit.

Datenspeicherung

stdio

Zwei Klartext-JSON-Dateien in deinem Home-Verzeichnis, erstellt mit Modus 0600 (nur Besitzer kann lesen/schreiben):

Lösche eine der Dateien, um den entsprechenden Status zurückzusetzen. Außer an myanimelist.net und api.myanimelist.net werden nirgendwo Daten gesendet.

Gehosteter Worker

Zwei Cloudflare-Speicheroberflächen:

OAUTH_KV (Workers KV-Namespace) — verwendet von @cloudflare/workers-oauth-provider und vom MAL-Autorisierungs-Relay:

• Registrierte OAuth-Clients (Dynamic Client Registration), Autorisierungsgenehmigungen und Zugriffs-/Aktualisierungstoken. Der Provider speichert Genehmigungs-props verschlüsselt; der Verschlüsselungsschlüssel ist in das ausgegebene Token selbst eingebettet, sodass KV-Snapshots allein nicht ausreichen, um die Props wiederherzustellen.

• Kurzlebige (10-Minuten-TTL) ausstehende MAL-Auth-Datensätze, die mit einem zufälligen State-String verschlüsselt sind. Jeder Datensatz enthält die ausstehende Autorisierungs-URL, deine MAL client_id/client_secret, den PKCE-Verifier und die Callback-URL. Einträge werden gelöscht, sobald der MAL-Callback sie verbraucht, oder laufen andernfalls automatisch ab. Sie werden als Klartext-JSON in KV gespeichert.

MAL_SESSION (Durable Object, eines pro Benutzer) — verschlüsselt mit u:<32-hex>, wobei der Hex-Wert die ersten 32 Zeichen von sha256("v1:" + mal_client_id + ":" + (mal_client_secret ?? "")) ist. Gespeichert als Klartext im SQLite-Speicher des DO (Cloudflare verschlüsselt DO-Speicher im Ruhezustand auf der Festplatte):

• config: deine MAL client_id und (falls ausgestellt) client_secret.

• tokens: MAL access_token, refresh_token, expires_at.

Zwei verschiedene MAL-Anmeldedatenpaare erzeugen zwei verschiedene Hashes → zwei vollständig getrennte Durable Objects ohne geteilten Status.

Was nicht gespeichert wird: Anime-/Manga-Listen, Benutzerprofildaten, Suchergebnisse oder alles andere, was von MAL zurückgegeben wird — diese fließen bei Bedarf direkt durch die Anfrage. Keine Analysen, keine Protokolle der Anfrageinhalte über die Standard-Cloudflare-Observability-Metriken hinaus.

Was über die Leitung übertragen wird: MAL client_id/client_secret werden als Formularfelder von deinem Browser über HTTPS an die Autorisierungsseite übermittelt. MAL-Zugriffstoken werden als Authorization: Bearer … an api.myanimelist.net weitergeleitet.

Zurücksetzen des Benutzerstatus: Widerrufe die Genehmigung von deinem MCP-Client aus (oder verbinde dich neu) oder kontaktiere den Operator, um das entsprechende Durable Object zu löschen. Eine erneute Autorisierung mit denselben MAL-Anmeldedaten verwendet dasselbe DO und seine vorhandenen Token wieder.

Umgebungsvariablen (nur stdio)

Bei gehosteten Worker-Bereitstellungen werden diese Umgebungsvariablen nicht verwendet; jeder Endbenutzer gibt seine eigenen MAL-Anmeldedaten über die Autorisierungsseite des Workers während der MCP-OAuth-Anmeldung an.

Entwicklung

bun run dev              # stdio, watch mode
bun run worker:dev       # Worker, local (miniflare)
bun run typecheck        # tsc --noEmit

Alle Tools akzeptieren einen optionalen fields-String, der direkt an MAL weitergegeben wird — siehe die Feld-Spezifikation, falls du die Standardwerte überschreiben musst.