Skip to main content
Glama

mcp-medusa

Servidor MCP que expone herramientas de automatización de anime de Medusa.

Herramientas

add_anime

Añade un anime a Medusa usando POST /api/v2/anime/add.

Argumentos comunes:

{
  "anime_id": 62076,
  "source": "myanimelist",
  "root_dir": "/media/videos/Anime",
  "anime": true,
  "scene": false,
  "status": "wanted",
  "initial_release_group": "SubsPlease",
  "fallback_release_groups": ["SubsPlease", "Erai-raws"],
  "release_group_fallback_days": 7
}

Argumentos:

Argumento

Obligatorio

Por defecto

Valores permitidos / notas

anime_id

sí

ninguno

ID de anime específico de la fuente. Para myanimelist, este es el ID de anime de MAL.

root_dir

sí

ninguno

Ruta del directorio raíz de Medusa para la nueva serie.

source

no

myanimelist

No distingue mayúsculas de minúsculas: myanimelist, livechart

anime

no

true

Normalmente, mantén true.

scene

no

false

Si se debe habilitar la numeración de escenas.

status

no

wanted

Cadena de estado de episodio de Medusa, comúnmente wanted, skipped o ignored.

initial_release_group

no

ninguno

Primer grupo de lanzamiento activo para incluir en la lista blanca, por ejemplo SubsPlease.

fallback_release_groups

no

ninguno

Lista ordenada de grupos de lanzamiento por los que rotar. Incluye el grupo inicial primero para un comportamiento determinista.

release_group_fallback_days

no

7

Días después de la fecha de emisión del episodio antes de cambiar al siguiente grupo de respaldo.

directory_name

no

generado por Medusa

Anulación opcional del nombre de la carpeta de la serie.

seasonal_anime

Consulta el anime estacional de Medusa usando GET /api/v2/anime/seasonal.

{
  "year": 2026,
  "season": "SPRING",
  "source": "myanimelist",
  "source_sort": "anime_num_list_users",
  "page": 1,
  "limit": 10,
  "fields": ["animeId", "displayTitle", "year", "animeType", "genres", "score", "imageUrl"]
}

Llamada mínima usando los valores predeterminados de la temporada de anime actual:

{}

Argumentos:

Argumento

Obligatorio

Por defecto

Valores permitidos / notas

year

no

año actual

Si se omite, se calcula a partir de la fecha actual del servidor MCP.

season

no

temporada de anime actual

No distingue mayúsculas de minúsculas: WINTER, SPRING, SUMMER, FALL o valores como Summer. Si se omite, se calcula a partir del mes actual del servidor MCP.

source

no

myanimelist

No distingue mayúsculas de minúsculas: myanimelist, livechart

source_sort

no

anime_num_list_users

No distingue mayúsculas de minúsculas: anime_num_list_users, anime_score

page

no

1

Número de página de resultados de Medusa. Debe ser 1 o mayor.

limit

no

10

Resultados por página. Medusa permite de 1 a 1000; el valor predeterminado es intencionadamente pequeño para evitar la truncación del cliente MCP.

fields

no

null

Lista opcional de campos de respuesta a conservar. Si se omite o es null, se devuelven los objetos de anime completos de Medusa.

Los valores predeterminados de la temporada de anime actual usan esta asignación de meses:

Meses

Temporada

Enero-marzo

WINTER

Abril-junio

SPRING

Julio-septiembre

SUMMER

Octubre-diciembre

FALL

Los valores útiles de fields incluyen:

["animeId", "source", "displayTitle", "titleRomanji", "titleEnglish", "year", "season", "animeType", "status", "episodes", "episodeInfo", "genres", "studios", "score", "numListUsers", "imageUrl", "anidbId", "tvdbId", "malId", "url", "directoryName"]

resolve_anime_title

Resuelve un título en candidatos enriquecidos de Medusa/MyAnimeList usando GET /api/v2/anime/search con source, includeDetails=true y limit.

{
  "title": "Frieren",
  "source": "myanimelist",
  "limit": 10,
  "min_score": 88,
  "score_gap": 8
}

Devuelve decision como match, ambiguous o no_match, junto con candidatos puntuados.

anime_info

Devuelve detalles compactos del anime y presencia en Medusa por título o ID de MAL sin añadir nada.

{
  "title": "Frieren",
  "source": "myanimelist"
}

o:

{
  "mal_id": 52991,
  "source": "myanimelist"
}

seasonal_candidates

Obtiene candidatos estacionales usando los filtros estacionales del lado del servidor de Medusa antes de aplicar heurísticas residuales específicas de OpenClaw.

{
  "year": 2026,
  "season": "SUMMER",
  "source": "myanimelist",
  "limit": 25,
  "min_num_list_users": 3000,
  "fields": ["animeId", "displayTitle", "animeType", "genres", "numListUsers", "synopsis"]
}

La herramienta MCP envía filtros de Medusa como animeType=TV, minNumListUsers, excludeGenres=Kids,Boys Love, matched=false, firstSeasonOnly=true y fields para reducir el tamaño de la carga útil.

prepare_seasonal_review

Compacta los elementos candidatos estacionales en un paquete de revisión para IA con instrucciones de revisión conservadoras.

{
  "items": [{"animeId": 62076, "displayTitle": "Example Title"}],
  "max_items": 25
}

resolve_and_add_anime

Resuelve y hace una prueba en seco o ejecuta una única adición a través del endpoint de adición masiva de Medusa. Las escrituras requieren execute: true.

{
  "title": "Frieren",
  "root_dir": "/media/videos/Anime",
  "execute": false
}

scheduler_status

Devuelve el estado de salud del hilo del programador de Medusa y el estado de la cola. Úsalo cuando las adiciones de anime parezcan atascadas o sin verificar.

{}

search_tvdb

Busca en TVDB por nombre de serie para obtener un ID de TVDB. Úsalo como respaldo cuando una adición de anime falla debido a problemas de mapeo de AniDB a TVDB.

{ "query": "Dorohedoro", "language": "en" }

add_series

Añade una serie directamente por ID de TVDB mediante POST /api/v2/series. Omite por completo la resolución de anime. Úsalo después de search_tvdb cuando add_anime falle.

Argumentos:

Argumento

Obligatorio

Por defecto

Notas

tvdb_id

sí

ninguno

ID de serie de TVDB (de search_tvdb).

root_dir

sí

ninguno

Ruta del directorio raíz de Medusa.

anime

no

true

status

no

wanted

Acepta cadenas como wanted, skipped, ignored — convertidas a numérico internamente.

language

no

ninguno

Anulación del idioma del indexador.

show_dir

no

ninguno

Anulación personalizada del nombre de la carpeta de la serie.

scene

no

false

paused

no

false

{ "tvdb_id": 370761, "root_dir": "/media/videos/Anime" }

set_episode_status

Establece los estados de episodio de una serie mediante POST /api/v2/internal/updateEpisodeStatus. Úsalo cuando los metadatos de TVDB no estén sincronizados y Medusa no esté descargando episodios que deberían estar disponibles.

Argumentos:

Argumento

Obligatorio

Por defecto

Notas

series_slug

sí

ninguno

Slug de la serie (p. ej. tvdb370761).

episodes

sí

ninguno

Lista de slugs de episodios (p. ej. ["s01e01", "s01e02"]).

status

no

wanted

Estado objetivo: wanted, skipped, ignored.

{ "series_slug": "tvdb370761", "episodes": ["s01e01", "s01e02"], "status": "wanted" }

Fuerza una búsqueda manual de episodios específicos mediante PUT /api/v2/search/manual. Pone en cola una búsqueda de proveedores que consulta activamente a los proveedores habilitados y captura los lanzamientos coincidentes. Úsalo después de establecer los episodios como «wanted».

Argumentos:

Argumento

Obligatorio

Por defecto

Notas

series_slug

sí

ninguno

Slug de la serie (p. ej. tvdb370761).

episodes

sí

ninguno

Lista de slugs de episodios (p. ej. ["s01e01", "s01e02"]).

{ "series_slug": "tvdb370761", "episodes": ["s01e01"] }

update_series_quality

Actualiza las calidades permitidas o preferidas de una serie existente mediante PATCH /api/v2/series/{slug}. Usa nombres de calidad legibles. Los campos omitidos se dejan sin cambios.

Argumentos:

Argumento

Obligatorio

Por defecto

Notas

series_slug

sí

ninguno

Slug de la serie (p. ej. tvdb370761).

allowed_qualities

no

ninguno

Nombres de calidad para la lista permitida.

preferred_qualities

no

ninguno

Nombres de calidad para la lista preferida.

Nombres de calidad: "SDTV", "SD DVD", "720p HDTV", "RawHD", "1080p HDTV", "720p WEB-DL", "1080p WEB-DL", "720p BluRay", "1080p BluRay", "4K UHD TV", "8K UHD TV", "4K UHD WEB-DL", "8K UHD WEB-DL", "4K UHD BluRay", "8K UHD BluRay".

{ "series_slug": "tvdb370761", "allowed_qualities": ["1080p BluRay", "720p HDTV"] }

organize_season_folders

Habilita las carpetas de temporada y mueve los archivos de episodios a subdirectorios Season XX/ sin renombrar archivos. Llama a POST /api/v2/series/{slug}/operation con type=ORGANIZE_SEASON_FOLDERS.

Úsalo cuando un anime de varias temporadas tenga todos los archivos en un directorio plano y Plex no muestre episodios debido a su escaso soporte de varias temporadas en una sola carpeta.

Argumentos:

Argumento

Obligatorio

Por defecto

Notas

series_slug

sí

ninguno

Slug de la serie (p. ej. tvdb370761).

{ "series_slug": "tvdb370761" }

postprocess

Activa el postprocesado manual de Medusa en un directorio. Escanea una carpeta de descarga/almacenamiento intermedio y mueve los episodios coincidentes a sus carpetas de serie. Reutiliza las credenciales MEDUSA_URL / MEDUSA_API_KEY. Úsalo para eliminar archivos atascados en el almacenamiento intermedio tras un postprocesado automático fallido (p. ej. un lanzamiento mal nombrado que el gestor de descargas abandonó). Llama a POST /api/v2/postprocess.

IMPORTANTE: el argumento directory es interpretado por el núcleo de Medusa, por lo que debe ser la ruta tal como se ve dentro del contenedor de Medusa (p. ej. /data/medusa), NO la ruta visible desde un contenedor Hermes separado.

Argumentos:

Argumento

Obligatorio

Por defecto

Notas

directory

no

/data/medusa

Ruta dentro del contenedor de Medusa a escanear. Debe coincidir con la vista del núcleo de Medusa, no con el montaje de Hermes.

process_type

no

auto

auto, manual o failed.

force_replace

no

false

Sobrescribe los archivos de episodios existentes.

process_method

no

copy

copy o move.

{ "proc_dir": "/data/medusa", "proc_type": "auto" }

bulk_add_anime

Hace una prueba en seco o ejecuta varias adiciones de anime a través de POST /api/v2/anime/bulk-add. Las escrituras requieren execute: true.

{
  "items": [{"animeId": 62076, "displayTitle": "Example Title", "aiDecision": "add"}],
  "decision_field": "aiDecision",
  "allowed_decisions": ["add"],
  "execute": false
}

Related MCP server: MyAnimeList MCP Server

Configuración

Variables de entorno:

Variable

Obligatorio

Descripción

MEDUSA_URL

sí

URL base de Medusa, por ejemplo http://medusa:8081

MEDUSA_API_KEY

recomendado

Clave API de Medusa enviada como X-Api-Key

MEDUSA_WEB_ROOT

no

Raíz web si Medusa está alojada bajo una ruta

MEDUSA_TIMEOUT

no

Tiempo de espera HTTP en segundos, por defecto 30

MCP_TRANSPORT

no

stdio o sse, por defecto stdio

MCP_HOST

no

Host de enlace SSE, por defecto 0.0.0.0

MCP_PORT

no

Puerto de enlace SSE, por defecto 8000

MCP_DNS_REBINDING_PROTECTION

no

Habilita la validación de Host/Origin del SDK de MCP, por defecto false

MCP_ALLOWED_HOSTS

no

Cabeceras Host permitidas separadas por comas cuando la protección contra rebinding de DNS está habilitada, por ejemplo daniel-nas.localdomain:3001,localhost:3001

MCP_ALLOWED_ORIGINS

no

Cabeceras Origin permitidas separadas por comas cuando la protección contra rebinding de DNS está habilitada

Para despliegues en contenedor/SSE, mantén MCP_HOST=0.0.0.0 o establécela explícitamente. La protección contra rebinding de DNS está deshabilitada por defecto porque, de lo contrario, los puertos mapeados, los proxies inversos y los nombres de host de la LAN suelen provocar errores 421 Misdirected Request. Si la habilitas, incluye el host y el puerto visibles externamente en MCP_ALLOWED_HOSTS.

Ejecutar localmente

pip install -e .
MEDUSA_URL=http://localhost:8081 MEDUSA_API_KEY=... mcp-medusa

Para SSE:

MEDUSA_URL=http://localhost:8081 MEDUSA_API_KEY=... mcp-medusa --transport sse --port 8000

Docker

La imagen usa SSE por defecto en el puerto 8000.

docker build -t mcp-medusa .
docker run --rm -p 8000:8000 \
  -e MEDUSA_URL=http://medusa:8081 \
  -e MEDUSA_API_KEY=... \
  mcp-medusa

Para stdio en su lugar:

docker run --rm -i \
  -e MEDUSA_URL=http://medusa:8081 \
  -e MEDUSA_API_KEY=... \
  mcp-medusa --transport stdio

CI/CD

El repositorio utiliza una canalización totalmente automatizada (sin pasos de publicación manuales):

  1. Abre un PR contra main. El flujo de trabajo ci.yml ejecuta tests/test_boot.py, que realmente inicia el servidor (stdio + SSE) y verifica que los constructores de FastMCP, las herramientas esperadas se registran y ambos transportes se enlazan. Esta es la compuerta que detecta fallos de arranque/importación antes de que se publiquen.

  2. Auto-fusión. Una vez que la prueba de arranque pasa, el trabajo enable-auto-merge fusiona el PR (squash) usando el secreto del repositorio ACTIONS_PAT (el GITHUB_TOKEN predeterminado no puede fusionar PRs en este repositorio).

  3. Auto-publicación + build. Hacer push a main activa merge-release.yml, que vuelve a ejecutar la prueba de arranque, crea una publicación con incremento de parche (v0.0.N+1) desde main, y construye + sube la imagen Docker en el mismo flujo de trabajo (el build está integrado en merge-release.yml en lugar de un flujo de trabajo separado activado por publicación, porque GitHub suprime el evento release: published cuando la publicación es creada por un flujo de trabajo mediante GITHUB_TOKEN).

Ejecutar las pruebas localmente

uv venv
uv pip install -e ".[test]"
uv run pytest tests/ -v

La prueba de arranque inicia el servidor real, por lo que no necesita Docker. Si cambias algo en la ruta de inicio de server.py, ejecuta esto antes de hacer push: CI bloqueará la fusión si el servidor no arranca.

Secretos requeridos

  • ACTIONS_PAT — un PAT de grano fino (o token repo clásico) con Contents: read+write y Pull requests: read+write, almacenado como secreto del repositorio. Usado por ci.yml para fusionar PRs. (El GITHUB_TOKEN predeterminado carece de capacidad de fusión aquí.)

  • DOCKER_USERNAME / DOCKER_PASSWORD — usados por docker-release.yml para subir la imagen.

Available Tools

21 tools
add_animeA

Add an anime series to Medusa via /api/v2/anime/add.

Note: Some anime may fail with "no name on TVDBv2" due to AniDB→TVDB ID mapping issues. As a workaround, use search_tvdb to find the correct TVDB ID, then add_series to add it directly.

Inputs: anime_id (required), root_dir (required), anime, scene, +7 more.

add_seriesA

Add a series to Medusa directly by TVDB ID via POST /api/v2/series.

Use this as a fallback when add_anime fails due to AniDB-to-TVDB mapping issues. First find the correct TVDB ID with search_tvdb, then add it here. This bypasses anime resolution entirely and adds via the standard series endpoint.

quality values: "N/A", "Unknown", "SDTV", "SD DVD", "720p HDTV", "RawHD", "1080p HDTV", "720p WEB-DL", "1080p WEB-DL", "720p BluRay", "1080p BluRay", "4K UHD TV", "8K UHD TV", "4K UHD WEB-DL", "8K UHD WEB-DL", "4K UHD BluRay", "8K UHD BluRay". When omitted, Medusa's global quality defaults are used.

Inputs: tvdb_id (required), root_dir (required), anime, scene, +6 more.

anime_infoA

Return compact anime details and Medusa presence by title or MAL ID. Does not add anime.

Inputs: limit, title, mal_id, source, +3 more. Returns: object

bulk_add_animeA

Dry-run or add multiple anime items. Skips filterDecision=skip; execute must be true for writes.

Inputs: items (required), source, execute, root_dir, +9 more. Returns: object

create_aliasA

Create a local scene exception (alias) for a series.

This enables Medusa to recognize an alternative release title when searching, allowing it to match releases that use a different naming scheme. Only local (user-managed) scene exceptions can be created via this tool.

Inputs: name (required), series_slug (required), season. Returns: object

delete_aliasB

Delete a scene exception (alias) by ID.

Inputs: alias_id (required). Returns: result

diagnose_release_groupsA

Diagnose release group issues for a series by comparing config vs available releases.

Checks provider cache first; if empty, triggers a manual search and retries. Returns a structured diagnosis with recommendation.

Inputs: series_slug (required), season, episode, max_retries, +1 more. Returns: object

get_aliasesA

List scene exceptions (aliases) for a series.

Scene exceptions are alternative episode/release titles that Medusa recognizes when searching. This tool reads them; use create_alias to add new ones.

Inputs: series_slug (required), season. Returns: result

organize_season_foldersA

Move episodes into Season XX/ subdirectories without renaming files.

Enables season folders on the series and moves all downloaded episode files into Season XX/ subdirectories, preserving original filenames. Also moves associated files (subtitles, etc.).

Use this when:

  • A multi-season anime has all files in a flat directory

  • Plex is missing episodes due to poor multi-season-in-one-folder support

  • A second season was added years later to a show originally added flat

Calls POST /api/v2/series/{slug}/operation with type=ORGANIZE_SEASON_FOLDERS.

Inputs: series_slug (required). Returns: object

postprocessA

Trigger Medusa manual post-processing on a directory.

Scans directory (a download/staging folder) and moves matched episodes into their show folders. Reuses Medusa credentials from MEDUSA_URL / MEDUSA_API_KEY. Use this to clear files stranded in staging after a failed auto-post-process (e.g. a mis-named release that the download handler bailed on).

IMPORTANT: directory is interpreted by MEDUSA CORE, so it must be the path as seen inside the Medusa container (e.g. /data/medusa), NOT the path visible from the Hermes container.

Inputs: directory, process_type, force_replace, process_method. Returns: object

prepare_seasonal_reviewC

Compact seasonal candidates into an AI review packet.

Inputs: items (required), max_items. Returns: object

resolve_and_add_animeB

Resolve and optionally add one anime. Dry-run unless execute is true.

Inputs: limit, title, mal_id, source, +10 more. Returns: object

resolve_anime_titleB

Resolve an anime title to MAL candidates with match/ambiguous/no_match decision.

Inputs: title (required), limit, fields, source, +2 more. Returns: object

scheduler_statusA

Return Medusa scheduler and queue status.

Shows whether each scheduler thread is alive, enabled, and currently active. Useful for diagnosing stuck queues.

Inputs: no named parameters. Returns: object

search_tvdbA

Search TVDB for a show by name and return matching TVDB IDs.

Use this when an anime add fails due to AniDB-to-TVDB mapping issues. Find the correct TVDB ID here, then add the show with add_series.

Inputs: query (required), language. Returns: result

seasonal_animeB

Query a paginated seasonal anime page from Medusa, optionally returning only selected fields.

Season, source, and source_sort are case-insensitive.

Inputs: page, year, limit, fields, +3 more.

seasonal_candidatesC

Fetch server-filtered seasonal anime candidates and apply residual preference heuristics.

Inputs: year, limit, fields, season, +5 more. Returns: object

set_episode_statusA

Set episode statuses for a series via PATCH /api/v2/episodes/{series_slug}.

Use when TVDB metadata is out of sync with actual episode status and Medusa is not downloading episodes that should be available. Set affected episodes to "wanted" to force Medusa to search for them.

Uses the same PATCH endpoint as the Medusa Web UI, so it can change UNAIRED episodes to WANTED unlike the internal bulk-update endpoint.

Inputs: episodes (required), series_slug (required), status. Returns: object

update_release_groupsA

Update release group configuration for a series.

Sends PATCH /api/v2/series/{slug} with the specified config.release.* fields. Only the provided fields are changed; omitted fields are left as-is.

Inputs: series_slug (required), blacklist, whitelist, fallback_days, +1 more. Returns: object

update_series_qualityA

Update allowed and/or preferred qualities for an existing series.

Sends PATCH /api/v2/series/{slug} with config.qualities.* fields. Only the provided fields are changed; omitted fields are left as-is.

quality values: "N/A", "Unknown", "SDTV", "SD DVD", "720p HDTV", "RawHD", "1080p HDTV", "720p WEB-DL", "1080p WEB-DL", "720p BluRay", "1080p BluRay", "4K UHD TV", "8K UHD TV", "4K UHD WEB-DL", "8K UHD WEB-DL", "4K UHD BluRay", "8K UHD BluRay".

Inputs: series_slug (required), allowed_qualities, preferred_qualities.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 21 tools

    Disambiguation3/5

    The core Medusa operations (aliases, release groups, searches, postprocessing) are clearly separated, but the anime-related tools have overlapping boundaries: seasonal_anime, seasonal_candidates, prepare_seasonal_review, resolve_anime_title, and resolve_and_add_anime all seem to cover similar discovery/dedup/resolution steps. Add flows are also split across add_series, add_anime, resolve_and_add_anime, and bulk_add_anime, so an agent may struggle to pick the right one without careful reading.

    Naming Consistency4/5

    Tool naming is overwhelmingly snake_case with a verb_noun pattern (create_alias, set_episode_status, update_series_quality, bulk_add_anime). Only a few tools deviate into noun-first or adjective-first forms such as anime_info and seasonal_anime, but the convention is still predictable overall.

    Tool Count3/5

    At 21 tools, the surface is on the upper edge of comfort and feels heavy for a cohesive server. The count is justifiable given the two intertwined domains of TV-series management and anime seasonal workflows, but some tools appear to cover niche pipeline stages that a smaller set could absorb.

    Completeness3/5

    The set covers many operational needs: adding series, adjusting statuses, searching, postprocessing, quality, season folders, aliases, scheduler status, and anime fetching. However, it lacks a general way to list or retrieve an existing series' slug/config, and there is no update path for aliases—only create/delete—so agents cannot fully reconcile or inspect existing state before modifying it.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers