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:

Argument	Required	Default	Allowed values / notes
anime_id	yes	none	Source-specific anime ID. For myanimelist, this is the MAL anime ID.
root_dir	yes	none	Medusa root directory path for the new series.
source	no	myanimelist	myanimelist, livechart
anime	no	true	Usually keep true.
scene	no	false	Whether to enable scene numbering.
status	no	wanted	Medusa episode status string, commonly wanted, skipped, or ignored.
initial_release_group	no	none	First/active release group to whitelist, for example SubsPlease.
fallback_release_groups	no	none	Ordered list of release groups to rotate through. Include the initial group first for deterministic behavior.
release_group_fallback_days	no	7	Days after episode airdate before switching to the next fallback group.
directory_name	no	Medusa-generated	Optional series folder name override.

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:

Argument	Required	Default	Allowed values / notes
year	no	current year	If omitted, calculated from the MCP server's current date.
season	no	current anime season	WINTER, SPRING, SUMMER, FALL. If omitted, calculated from the MCP server's current month.
source	no	myanimelist	myanimelist, livechart
source_sort	no	anime_num_list_users	anime_num_list_users, anime_score
page	no	1	Medusa result page number. Must be 1 or greater.
limit	no	10	Results per page. Medusa allows 1 through 1000; default is intentionally small to avoid MCP client truncation.
fields	no	null	Optional list of response fields to keep. If omitted/null, the full Medusa anime objects are returned.

Current anime season defaults use this month mapping:

Months	Season
January-March	WINTER
April-June	SPRING
July-September	SUMMER
October-December	FALL

Useful fields values include:

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

Configuration

Environment variables:

Variable	Required	Description
MEDUSA_URL	yes	Base URL for Medusa, for example http://medusa:8081
MEDUSA_API_KEY	recommended	Medusa API key sent as X-Api-Key
MEDUSA_WEB_ROOT	no	Web root if Medusa is hosted below a path
MEDUSA_TIMEOUT	no	HTTP timeout in seconds, default 30
MCP_TRANSPORT	no	stdio or sse, default stdio
MCP_HOST	no	SSE bind host, default 0.0.0.0
MCP_PORT	no	SSE bind port, default 8000
MCP_DNS_REBINDING_PROTECTION	no	Enable MCP SDK Host/Origin validation, default false
MCP_ALLOWED_HOSTS	no	Comma-separated allowed Host headers when DNS rebinding protection is enabled, for example daniel-nas.localdomain:3001,localhost:3001
MCP_ALLOWED_ORIGINS	no	Comma-separated allowed Origin headers when DNS rebinding protection is enabled

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