mal-mcp

Un servidor del Protocolo de Contexto de Modelo que expone la API v2 de MyAnimeList a Claude y otros clientes compatibles con MCP. Escrito en TypeScript, se ejecuta localmente mediante Bun a través de stdio o se despliega en Cloudflare Workers como un servidor multiusuario alojado.

Herramientas

Configuración

• configure — solo stdio — almacena el client_id (y client_secret si se emitió) de MyAnimeList del usuario. Debe llamarse antes que cualquier otra herramienta. No está registrado en el Worker; en el Worker, cada usuario inicia sesión a través del flujo OAuth de MCP cuando añade el servidor a su cliente.

• authenticate — solo stdio (significativo) — inicia el flujo OAuth de MAL; abre un navegador y espera la devolución de llamada local. En el Worker, esto es una operación nula mantenida por compatibilidad: la autenticación ocurre automáticamente al conectarse mediante OAuth de MCP.

• get_auth_status — comprueba si las credenciales y los tokens de usuario están disponibles.

Público (solo Client ID)

• search_anime — buscar anime por título

• get_anime_details — detalles completos de un ID de anime

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

• get_seasonal_anime — anime por año + temporada

• search_manga — buscar manga por título

• get_manga_details — detalles completos de un ID de manga

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

Con ámbito de usuario (se requiere token de acceso OAuth2)

• get_current_user — perfil + estadísticas de anime para el usuario autenticado

• get_anime_suggestions — recomendaciones de anime personalizadas

• get_user_anime_list — leer la lista de anime pública de cualquier usuario (o @me)

• update_anime_list_status — añadir / actualizar el estado de la lista, puntuación, episodios vistos, etc.

• delete_anime_list_item — eliminar un anime de tu lista

• get_user_manga_list — leer la lista de manga pública de cualquier usuario (o @me)

• update_manga_list_status — añadir / actualizar el estado de la lista, puntuación, capítulos leídos, etc.

• delete_manga_list_item — eliminar un manga de tu lista

Related MCP server: Claude Code MCP

Opción 1: Ejecutar localmente a través de stdio

1. Instalación

bun install

2. Conectarlo a tu cliente MCP

Añádelo a claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

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

Para Claude Code, usa claude mcp add o coloca el bloque equivalente en .claude/mcp.json.

3. Configura tus credenciales de MAL

Crea un cliente de API en https://myanimelist.net/apiconfig:

• Tipo de aplicación: other / web

• URL de redirección de la aplicación: http://localhost:8765/callback

Luego, desde tu cliente MCP, llama a la herramienta configure con tu client_id (y client_secret si MAL emitió uno). Las credenciales se guardan en ~/.mal-mcp-config.json.

4. (Opcional) Autorizar para herramientas con ámbito de usuario

Llama a authenticate desde tu cliente MCP. Se abrirá un navegador, apruebas la solicitud, el servidor local en el puerto 8765 captura la redirección y los tokens se guardan en ~/.mal-mcp-tokens.json. El servidor los actualiza automáticamente desde allí.

Si prefieres una CLI:

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

Opción 2: Alojar en Cloudflare Workers (multiusuario, MCP OAuth)

Un único Worker sirve a cada usuario bajo el estándar MCP OAuth 2.1 (Registro Dinámico de Clientes). Una URL para todos: https://mal-mcp.<account>.workers.dev/mcp. Durante el inicio de sesión, cada usuario proporciona su propio client_id (y client_secret si se emitió) de MAL; el estado por usuario reside en un Durable Object identificado por un hash de esas credenciales.

1. Configuración del operador (una vez)

bun install
bunx wrangler login
bunx wrangler kv namespace create OAUTH_KV

Pega el id del espacio de nombres devuelto en wrangler.jsonc (reemplaza REPLACE_WITH_KV_ID), luego despliega:

bun run worker:deploy

Para desarrollo local:

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

2. Cada usuario se conecta

1. Crea un cliente de API de MAL en https://myanimelist.net/apiconfig (Tipo de aplicación: other). Establece la URL de redirección de la aplicación en:

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

   (Esta URL exacta: la misma para cada usuario de un despliegue determinado.)

2. Añade el servidor MCP a tu cliente:

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

   O equivalentemente en la configuración:

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

3. Tu cliente MCP abrirá una pestaña del navegador en la primera conexión. La página de autorización del Worker solicita tu client_id (y client_secret si se emitió) de MAL, te redirige a MyAnimeList para aprobar y luego te devuelve a tu cliente MCP, ahora con la sesión iniciada. Los tokens de acceso y actualización se guardan en tu Durable Object; el token de acceso de MAL se actualiza automáticamente.

Notas de seguridad para despliegues alojados

• El Worker es su propio servidor de autorización OAuth 2.1 para MCP. Los tokens de portador emitidos a tu cliente MCP tienen un ámbito limitado a ti; filtrar uno permite al portador llamar a MAL en tu nombre hasta que el token expire.

• Diferentes credenciales de MAL → diferente Durable Object → estado totalmente separado. No hay estado compartido entre usuarios.

• El Worker no posee credenciales de MAL propias; cada usuario proporciona su propio cliente de API de MAL.

Almacenamiento de datos

stdio

Dos archivos JSON de texto plano en tu directorio personal, creados con el modo 0600 (solo lectura/escritura del propietario):

Elimina cualquiera de los archivos para restablecer el estado correspondiente. No se envía nada a ningún lugar aparte de myanimelist.net y api.myanimelist.net.

Worker alojado

Dos superficies de almacenamiento de Cloudflare:

OAUTH_KV (espacio de nombres de Workers KV) — utilizado por @cloudflare/workers-oauth-provider y por el relé de autorización de MAL:

• Clientes OAuth registrados (Registro Dinámico de Clientes), concesiones de autorización y tokens de acceso/actualización. El proveedor almacena las props de la concesión cifradas; la clave de cifrado se envuelve en el propio token emitido, por lo que las instantáneas de KV por sí solas no son suficientes para recuperar las propiedades.

• Registros pendientes de autenticación de MAL de corta duración (TTL de 10 minutos) identificados por una cadena de estado aleatoria. Cada registro contiene la URL de autorización pendiente, tu client_id/client_secret de MAL, el verificador PKCE y la URL de devolución de llamada. Las entradas se eliminan tan pronto como la devolución de llamada de MAL las consume, o expiran automáticamente de lo contrario. Se almacenan como JSON de texto plano en KV.

MAL_SESSION (Durable Object, uno por usuario) — identificado por u:<32-hex> donde el hex es los primeros 32 caracteres de sha256("v1:" + mal_client_id + ":" + (mal_client_secret ?? "")). Almacenado como texto plano en el almacenamiento SQLite del DO (Cloudflare cifra el almacenamiento del DO en reposo en el disco):

• config: tu client_id de MAL y (si se emitió) client_secret.

• tokens: access_token, refresh_token, expires_at de MAL.

Dos pares de credenciales de MAL diferentes producen dos hashes diferentes → dos Durable Objects totalmente separados sin estado compartido.

Lo que no se almacena: listas de anime/manga, datos de perfil de usuario, resultados de búsqueda o cualquier otra cosa devuelta por MAL; eso fluye directamente a través de la solicitud bajo demanda. Sin analíticas, sin registros de contenido de solicitudes más allá de las métricas de observabilidad estándar de Cloudflare.

Lo que viaja por la red: el client_id/client_secret de MAL se envían como campos de formulario desde tu navegador a la página de autorización a través de HTTPS. Los tokens de acceso de MAL se reenvían como Authorization: Bearer … a api.myanimelist.net.

Restablecer el estado de un usuario: revoca la concesión desde tu cliente MCP (o vuelve a conectar), o contacta al operador para eliminar el Durable Object correspondiente. Volver a autorizar con las mismas credenciales de MAL reutilizará el mismo DO y sus tokens existentes.

Variables de entorno (solo stdio)

En despliegues de Worker alojados, estas variables de entorno no se utilizan; cada usuario final proporciona sus propias credenciales de MAL a través de la página de autorización del Worker durante el inicio de sesión de MCP OAuth.

Desarrollo

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

Todas las herramientas aceptan una cadena fields opcional que pasa directamente a MAL; consulta la especificación de campos si necesitas anular los valores predeterminados.