mcp-medusa

MCP server that exposes Medusa anime automation tools.

Tools

add_anime

Adds an anime to Medusa using POST /api/v2/anime/add.

Common arguments:

{
  "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
}

Arguments:

seasonal_anime

Queries Medusa seasonal anime using 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"]
}

Minimal call using current anime season defaults:

{}

Arguments:

Current anime season defaults use this month mapping:

Useful fields values include:

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

resolve_anime_title

Resolves a title to enriched Medusa/MyAnimeList candidates using GET /api/v2/anime/search with source, includeDetails=true, and limit.

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

Returns decision as match, ambiguous, or no_match, plus scored candidates.

anime_info

Returns compact anime details and Medusa presence by title or MAL ID without adding anything.

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

or:

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

seasonal_candidates

Fetches seasonal candidates using Medusa's server-side seasonal filters before applying residual OpenClaw-specific heuristics.

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

The MCP tool sends Medusa filters such as animeType=TV, minNumListUsers, excludeGenres=Kids,Boys Love, matched=false, firstSeasonOnly=true, and fields to reduce payload size.

prepare_seasonal_review

Compacts seasonal candidate items into an AI review packet with conservative review instructions.

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

resolve_and_add_anime

Resolves and dry-runs or executes a single add through Medusa's bulk-add endpoint. Writes require execute: true.

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

scheduler_status

Returns Medusa scheduler thread health and queue state. Use when anime adds appear stuck or unverified.

{}

search_tvdb

Searches TVDB by show name for a TVDB ID. Use as fallback when an anime add fails due to AniDB-to-TVDB mapping issues.

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

add_series

Adds a series directly by TVDB ID via POST /api/v2/series. Bypasses anime resolution entirely. Use after search_tvdb when add_anime fails.

Arguments:

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

set_episode_status

Sets episode statuses for a series via POST /api/v2/internal/updateEpisodeStatus. Use when TVDB metadata is out of sync and Medusa is not downloading episodes that should be available.

Arguments:

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

force_search

Force a manual search for specific episodes via PUT /api/v2/search/manual. Queues a provider search that actively queries enabled providers and snatches matching releases. Use after setting episodes to "wanted".

Arguments:

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

update_series_quality

Update allowed or preferred qualities for an existing series via PATCH /api/v2/series/{slug}. Uses human-readable quality names. Omitted fields are left unchanged.

Arguments:

Quality names: "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

Enable season folders and move episode files into Season XX/ subdirectories without renaming files. Calls POST /api/v2/series/{slug}/operation with type=ORGANIZE_SEASON_FOLDERS.

Use when a multi-season anime has all files in a flat directory and Plex is missing episodes due to poor multi-season-in-one-folder support.

Arguments:

{ "series_slug": "tvdb370761" }

bulk_add_anime

Dry-runs or executes multiple anime adds through POST /api/v2/anime/bulk-add. Writes require execute: true.

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

Related MCP server: Bangumi TV MCP Service

Configuration

Environment variables:

For container/SSE deployments, keep MCP_HOST=0.0.0.0 or set it explicitly. DNS rebinding protection is disabled by default because mapped ports, reverse proxies, and LAN hostnames otherwise commonly cause 421 Misdirected Request errors. If you enable it, include the externally visible host and port in MCP_ALLOWED_HOSTS.

Run locally

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

For SSE:

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

Docker

The image defaults to SSE on port 8000.

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

For stdio instead:

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