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 HTTP, stdio, or SSE transports. All Overseerr API authentication is handled server-side — clients only need a Bearer token for the MCP endpoint itself.

What this repository ships

• overseerr_mcp/: FastMCP server and Overseerr HTTP client
• .claude-plugin/, .codex-plugin/, gemini-extension.json: client manifests
• skills/overseerr/: Claude-facing skill docs
• docker-compose.yml, Dockerfile, entrypoint.sh: container deployment
• docs/overseerr-api.yaml: bundled Overseerr API reference
• scripts/: linting, Docker, and smoke-test helpers

Tools

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

search_media

Search for movies or TV shows by title.

Response schema — each item in the returned list:

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.

Key response fields:

mediaInfo fields:

Example:

get_movie_details(tmdb_id=438631)

get_tv_show_details

Fetch detailed information for a TV show from Overseerr. Includes season list — use the season numbers here to scope a request_tv_show call.

Key response fields:

Example:

get_tv_show_details(tmdb_id=1396)

request_movie

Submit a movie request to Overseerr. Overseerr forwards the request to Radarr for download.

Response fields:

Example:

request_movie(tmdb_id=438631)

request_tv_show

Submit a TV show request. Optionally request specific seasons. Omitting seasons requests all seasons.

Examples:

# Request all seasons
request_tv_show(tmdb_id=1396)

# Request only seasons 1 and 2
request_tv_show(tmdb_id=1396, seasons=[1, 2])

# Request a single season
request_tv_show(tmdb_id=1396, seasons=[4])

Season numbers come from get_tv_show_details → seasons[].seasonNumber. Season 0 is typically specials; omit it unless specifically wanted.

list_failed_requests

List media requests that have entered a failed state. Results are sorted by most recently modified.

Response fields — each item in the returned list:

Pagination examples:

# First page
list_failed_requests(count=20)

# Second page
list_failed_requests(count=20, skip=20)

# Third page
list_failed_requests(count=20, skip=40)

Returns the string "No failed requests found." when the list is empty.

overseerr_help

Returns the built-in markdown help document covering all tools and parameters.

overseerr_help()

TMDB ID

The TMDB ID is The Movie Database's integer identifier for a specific title. It is the primary key used by Overseerr and all tools in this server.

• Always search first with search_media. The tmdbId field in each result is what you pass to all other tools.
• Never guess or construct a TMDB ID manually.
• The same integer is used for both movies and TV shows — the mediaType field distinguishes them.

Example: searching for "Dune: Part Two" returns tmdbId: 693134. Use that value directly in get_movie_details(tmdb_id=693134) and request_movie(tmdb_id=693134).

Request Status

Overseerr uses integer status codes for request and media state. These appear in request_movie / request_tv_show responses and list_failed_requests output.

Approval workflow:

After request_movie or request_tv_show, the request enters pending (1) unless the Overseerr instance has auto-approval enabled for the requesting user. Once approved (2), Overseerr sends the request to Radarr (movies) or Sonarr (TV). When the download completes and Plex/Jellyfin picks it up, the status advances to available (4). A failed (8) status means an error in the download pipeline — report the title and request ID to the admin.

Complete Workflow Example

# 1. Search by title
search_media(query="Dune: Part Two")
# → returns [{tmdbId: 693134, mediaType: "movie", title: "Dune: Part Two", year: "2024", ...}]

# 2. Inspect details to confirm and check existing request status
get_movie_details(tmdb_id=693134)
# → returns full movie object with mediaInfo.status showing current state

# 3. Submit the request
request_movie(tmdb_id=693134)
# → returns {id: 42, status: 1, media: {tmdbId: 693134, ...}, ...}
# status 1 = pending approval

# 4. For a TV show, check seasons first
get_tv_show_details(tmdb_id=1396)
# → returns show object with seasons list showing seasonNumber values

# 5. Request specific seasons
request_tv_show(tmdb_id=1396, seasons=[1, 2, 3])

# 6. Review any download failures
list_failed_requests(count=20)

Installation

Marketplace

/plugin marketplace add jmagar/claude-homelab
/plugin install overseerr-mcp @jmagar-claude-homelab

Local development

uv sync --dev
uv run overseerr-mcp-server

Alternative entrypoint:

uv run python -m overseerr_mcp

Configuration

Copy .env.example to .env and fill in required values:

cp .env.example .env
# or: just setup

Environment variables

OVERSEERR_URL and OVERSEERR_API_KEY are required — the server exits at startup if either is missing.

Transport modes

For HTTP transports, the MCP endpoint is served at /mcp. Requests must include Authorization: Bearer <OVERSEERR_MCP_TOKEN> unless OVERSEERR_MCP_NO_AUTH=true.

For sse, the endpoint is served at /sse.

Authentication

Generate a token:

just gen-token
# or: openssl rand -hex 32

Set OVERSEERR_MCP_TOKEN in .env to that value. Configure your MCP client to send:

Authorization: Bearer <token>

The /health endpoint is always unauthenticated — it is used for Docker healthchecks.

Error handling

All tools return an error string beginning with "Error:" when something goes wrong. Common errors:

Always check whether the return value is a string before treating it as a dict or list.

Development

just dev          # run server locally
just lint         # ruff check
just fmt          # ruff format
just typecheck    # ty check
just test         # run tests
just up           # docker compose up -d
just logs         # docker compose logs -f
just health       # curl /health
just test-live    # end-to-end live test (requires running server)
just gen-token    # generate a bearer token
just check-contract  # plugin contract lint

Verification

Run after changes:

just lint
just typecheck
just test
just health

For a live end-to-end check against a running server:

just test-live

Related plugins

License

MIT