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

postprocess

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

IMPORTANT: the directory argument 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 a separate Hermes container.

Arguments:

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

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: MyAnimeList MCP Server

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

CI/CD

The repo uses a fully automated pipeline (no manual release steps):

1. Open a PR against main. The ci.yml workflow runs tests/test_boot.py, which actually starts the server (stdio + SSE) and asserts FastMCP constructs, the expected tools register, and both transports bind. This is the gate that catches boot/import crashes before they ship.

2. Auto-merge. Once the boot test passes, the enable-auto-merge job merges the PR (squash) using the ACTIONS_PAT repo secret (the default GITHUB_TOKEN cannot merge PRs in this repo).

3. Auto-release + build. Pushing to main triggers merge-release.yml, which re-runs the boot test, creates a patch-bumped release (v0.0.N+1) off main, and builds + pushes the Docker image in the same workflow (the build is folded into merge-release.yml rather than a separate release-triggered workflow, because GitHub suppresses the release: published event when the release is created by a workflow via GITHUB_TOKEN).

Running the tests locally

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

The boot test spawns the real server, so it needs no Docker. If you change anything in server.py startup path, run this before pushing — CI will block the merge if the server fails to boot.

Required secrets

• ACTIONS_PAT — a fine-grained PAT (or classic repo token) with Contents: read+write and Pull requests: read+write, stored as a repo secret. Used by ci.yml to merge PRs. (The default GITHUB_TOKEN lacks merge capability here.)

• DOCKER_USERNAME / DOCKER_PASSWORD — used by docker-release.yml to push the image.