mcp-medusa
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 |
| sí | ninguno | ID de anime específico de la fuente. Para |
| sí | ninguno | Ruta del directorio raíz de Medusa para la nueva serie. |
| no |
| No distingue mayúsculas de minúsculas: |
| no |
| Normalmente, mantén |
| no |
| Si se debe habilitar la numeración de escenas. |
| no |
| Cadena de estado de episodio de Medusa, comúnmente |
| no | ninguno | Primer grupo de lanzamiento activo para incluir en la lista blanca, por ejemplo |
| no | ninguno | Lista ordenada de grupos de lanzamiento por los que rotar. Incluye el grupo inicial primero para un comportamiento determinista. |
| no |
| Días después de la fecha de emisión del episodio antes de cambiar al siguiente grupo de respaldo. |
| 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 |
| no | año actual | Si se omite, se calcula a partir de la fecha actual del servidor MCP. |
| no | temporada de anime actual | No distingue mayúsculas de minúsculas: |
| no |
| No distingue mayúsculas de minúsculas: |
| no |
| No distingue mayúsculas de minúsculas: |
| no |
| Número de página de resultados de Medusa. Debe ser |
| no |
| Resultados por página. Medusa permite de |
| no |
| Lista opcional de campos de respuesta a conservar. Si se omite o es |
Los valores predeterminados de la temporada de anime actual usan esta asignación de meses:
Meses | Temporada |
Enero-marzo |
|
Abril-junio |
|
Julio-septiembre |
|
Octubre-diciembre |
|
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 |
| sí | ninguno | ID de serie de TVDB (de |
| sí | ninguno | Ruta del directorio raíz de Medusa. |
| no |
| |
| no |
| Acepta cadenas como |
| no | ninguno | Anulación del idioma del indexador. |
| no | ninguno | Anulación personalizada del nombre de la carpeta de la serie. |
| no |
| |
| no |
|
{ "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 |
| sí | ninguno | Slug de la serie (p. ej. |
| sí | ninguno | Lista de slugs de episodios (p. ej. |
| no |
| Estado objetivo: |
{ "series_slug": "tvdb370761", "episodes": ["s01e01", "s01e02"], "status": "wanted" }force_search
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 |
| sí | ninguno | Slug de la serie (p. ej. |
| sí | ninguno | Lista de slugs de episodios (p. ej. |
{ "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 |
| sí | ninguno | Slug de la serie (p. ej. |
| no | ninguno | Nombres de calidad para la lista permitida. |
| 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 |
| sí | ninguno | Slug de la serie (p. ej. |
{ "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 |
| no |
| Ruta dentro del contenedor de Medusa a escanear. Debe coincidir con la vista del núcleo de Medusa, no con el montaje de Hermes. |
| no |
|
|
| no |
| Sobrescribe los archivos de episodios existentes. |
| no |
|
|
{ "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 |
| sí | URL base de Medusa, por ejemplo |
| recomendado | Clave API de Medusa enviada como |
| no | Raíz web si Medusa está alojada bajo una ruta |
| no | Tiempo de espera HTTP en segundos, por defecto |
| no |
|
| no | Host de enlace SSE, por defecto |
| no | Puerto de enlace SSE, por defecto |
| no | Habilita la validación de Host/Origin del SDK de MCP, por defecto |
| no | Cabeceras |
| no | Cabeceras |
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-medusaPara SSE:
MEDUSA_URL=http://localhost:8081 MEDUSA_API_KEY=... mcp-medusa --transport sse --port 8000Docker
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-medusaPara stdio en su lugar:
docker run --rm -i \
-e MEDUSA_URL=http://medusa:8081 \
-e MEDUSA_API_KEY=... \
mcp-medusa --transport stdioCI/CD
El repositorio utiliza una canalización totalmente automatizada (sin pasos de publicación manuales):
Abre un PR contra
main. El flujo de trabajoci.ymlejecutatests/test_boot.py, que realmente inicia el servidor (stdio + SSE) y verifica que los constructores deFastMCP, 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.Auto-fusión. Una vez que la prueba de arranque pasa, el trabajo
enable-auto-mergefusiona el PR (squash) usando el secreto del repositorioACTIONS_PAT(elGITHUB_TOKENpredeterminado no puede fusionar PRs en este repositorio).Auto-publicación + build. Hacer push a
mainactivamerge-release.yml, que vuelve a ejecutar la prueba de arranque, crea una publicación con incremento de parche (v0.0.N+1) desdemain, y construye + sube la imagen Docker en el mismo flujo de trabajo (el build está integrado enmerge-release.ymlen lugar de un flujo de trabajo separado activado por publicación, porque GitHub suprime el eventorelease: publishedcuando la publicación es creada por un flujo de trabajo medianteGITHUB_TOKEN).
Ejecutar las pruebas localmente
uv venv
uv pip install -e ".[test]"
uv run pytest tests/ -vLa 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 tokenrepoclásico) con Contents: read+write y Pull requests: read+write, almacenado como secreto del repositorio. Usado porci.ymlpara fusionar PRs. (ElGITHUB_TOKENpredeterminado carece de capacidad de fusión aquí.)DOCKER_USERNAME/DOCKER_PASSWORD— usados pordocker-release.ymlpara subir la imagen.
Available Tools
21 toolsadd_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
force_searchA
Force a manual search for specific episodes via PUT /api/v2/search/manual.
Queues a manual search that actively queries providers and snatches matching releases. Use after setting episode status to "wanted" when you want to immediately search for and download episodes.
Inputs: episodes (required), series_slug (required).
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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
Unofficial AniList MCP — wraps AniList GraphQL API (free, no auth)
Anime Garden MCP for anime torrent discovery.
Unofficial Jikan MCP — wraps the Jikan v4 API (anime/manga data, free, no auth)
TVMaze MCP — TV show metadata, episodes, schedules (no auth)
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides MCP access to the BangumiTV API, allowing users to retrieve and interact with anime, manga, music, and game information through natural language queries.1727-
- AlicenseBqualityDmaintenanceMCP Server for interacting with the MyAnimeList API, allowing LLM clients to access and interact with anime, manga and more.154MIT
- AlicenseNot gradedqualityAmaintenanceEnables searching Overseerr media, retrieving TMDB-backed details, and submitting movie or TV requests through MCP tools.5MIT
- AlicenseBqualityDmaintenanceEnables control and management of a self-hosted media stack (Radarr, Sonarr, Prowlarr, SABnzbd, qBittorrent) through natural language via MCP.15GPL 3.0