Overseerr MCP

MCP server for searching Overseerr media, retrieving TMDB-backed details, and submitting movie or TV requests from Claude, Codex, or any MCP client.

Overview

The server talks to an existing Overseerr instance via its REST API and exposes MCP tools over stdio (default) or HTTP transports. All Overseerr API authentication is handled server-side — clients only need a Bearer token for the MCP endpoint itself when using HTTP transport.

What this repository ships

• overseerr_mcp/: FastMCP server and Overseerr HTTP client
• .claude-plugin/, .codex-plugin/, gemini-extension.json: client manifests
• skills/: Claude-facing skill docs for Overseerr and bundled media services
• bin/: plugin executables (load-env, sync-urls, extract-keys, etc.)
• docker-compose.yml, Dockerfile, entrypoint.sh: container deployment
• docs/: ENV variable reference and upstream API spec

Tools

Tool	Purpose
search_media	Search movies or TV shows by title
get_movie_details	Fetch full movie details by TMDB ID
get_tv_show_details	Fetch full TV show details (including seasons) by TMDB ID
request_movie	Submit a movie request
request_tv_show	Submit a TV request, optionally scoped to specific seasons
list_failed_requests	List failed requests with pagination
overseerr_help	Return built-in markdown help for all tools

The server also exposes GET /health (unauthenticated) for liveness checks.

search_media

Search for movies or TV shows by title.

Parameter	Type	Required	Default	Description
query	string	yes	—	Title or keyword to search
media_type	string	no	null	"movie" or "tv" — searches both if omitted

Response schema — each item in the returned list:

Field	Type	Description
tmdbId	int	TMDB integer ID (use this for all subsequent tool calls)
mediaType	string	"movie" or "tv"
title	string	Display title (falls back to name or originalName for TV)
year	string	Release or first-air year (e.g. "2021"), null if unknown
overview	string	Plot summary
posterPath	string	TMDB poster path (relative, e.g. /abc123.jpg)

Examples:

search_media(query="Dune")
search_media(query="Breaking Bad", media_type="tv")
search_media(query="Inception", media_type="movie")

Returns an error string if no results match or if the Overseerr API fails.

get_movie_details

Fetch detailed information for a movie from Overseerr. Returns the full Overseerr/TMDB movie object including cast, genres, runtime, status, and current request state.

Parameter	Type	Required	Description
tmdb_id	int	yes	TMDB integer ID from search_media results

Key response fields:

Field	Type	Description
id	int	TMDB ID
title	string	Movie title
releaseDate	string	ISO date ("2021-10-22")
runtime	int	Runtime in minutes
overview	string	Plot summary
genres	list	Genre objects with id and name
status	string	TMDB release status (e.g. "Released")
mediaInfo	object	Overseerr request/availability state (see below)
credits	object	cast and crew arrays
posterPath	string	TMDB poster path

mediaInfo fields:

Field	Type	Description
status	int	Overseerr media status code (see Request Status)
requests	list	Existing request objects for this media
downloadStatus	list	Radarr/

... View full README on GitHub