Server data from the Official MCP Registry
MCP server for Overseerr media requests and discovery.
MCP server for Overseerr media requests and discovery.
Valid MCP server (0 strong, 4 medium validity signals). No known CVEs in dependencies. Imported from the Official MCP Registry. Trust signals: trusted author (4/4 approved). 1 finding(s) downgraded by scanner intelligence.
14 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: OVERSEERR_URL
Environment variable: OVERSEERR_API_KEY
Add this to your MCP configuration file:
{
"mcpServers": {
"tv-tootie-overseerr-mcp": {
"env": {
"OVERSEERR_URL": "your-overseerr-url-here",
"OVERSEERR_API_KEY": "your-overseerr-api-key-here"
},
"args": [
"overseerr-mcp"
],
"command": "uvx"
}
}
}From the project's GitHub README.
MCP server for searching Overseerr media, retrieving TMDB-backed details, and submitting movie or TV requests from Claude, Codex, or any MCP client.
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.
overseerr_mcp/: FastMCP server and Overseerr HTTP client.claude-plugin/, .codex-plugin/, gemini-extension.json: client manifestsskills/: Claude-facing skill docs for Overseerr and bundled media servicesbin/: plugin executables (load-env, sync-urls, extract-keys, etc.)docker-compose.yml, Dockerfile, entrypoint.sh: container deploymentdocs/: ENV variable reference and upstream API spec| 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 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.
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/Sonarr download state |
Example:
get_movie_details(tmdb_id=438631)
Fetch detailed information for a TV show from Overseerr. Includes season list — use the season numbers here to scope a request_tv_show call.
| 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 |
name | string | Show title |
firstAirDate | string | ISO date of first episode |
numberOfSeasons | int | Total season count |
numberOfEpisodes | int | Total episode count |
overview | string | Plot summary |
genres | list | Genre objects with id and name |
status | string | TMDB show status (e.g. "Ended", "Returning Series") |
seasons | list | Season objects with seasonNumber, episodeCount, airDate |
mediaInfo | object | Overseerr request/availability state |
Example:
get_tv_show_details(tmdb_id=1396)
Submit a movie request to Overseerr. Overseerr forwards the request to Radarr for download.
| Parameter | Type | Required | Description |
|---|---|---|---|
tmdb_id | int | yes | TMDB integer ID for the movie to request |
Response fields:
| Field | Type | Description |
|---|---|---|
id | int | Overseerr request ID |
status | int | Request status code (see Request Status) |
media | object | Media object with tmdbId, mediaType, and availability state |
requestedBy | object | User who submitted the request |
createdAt | string | ISO timestamp |
modifiedAt | string | ISO timestamp of last status change |
Example:
request_movie(tmdb_id=438631)
Submit a TV show request. Optionally request specific seasons. Omitting seasons requests all seasons.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
tmdb_id | int | yes | — | TMDB integer ID for the TV show |
seasons | list[int] | no | null | Season numbers to request; omit to request all |
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 media requests that have entered a failed state. Results are sorted by most recently modified.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
count | int | no | 10 | Number of results to return |
skip | int | no | 0 | Number of results to skip (for pagination) |
Response fields — each item in the returned list:
| Field | Type | Description |
|---|---|---|
requestId | int | Overseerr request ID |
status | int | Request status code (see Request Status) |
type | string | "movie" or "tv" |
tmdbId | int | TMDB ID of the media |
title | string | Media title |
requested_by | string | Display name of the requesting user |
requested_at | string | ISO timestamp of initial request |
modified_at | string | ISO timestamp of last status change |
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.
Returns the built-in markdown help document covering all tools and parameters.
overseerr_help()
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.
search_media. The tmdbId field in each result is what you pass to all other tools.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).
Overseerr uses integer status codes for request and media state. These appear in request_movie / request_tv_show responses and list_failed_requests output.
| Code | Name | Meaning |
|---|---|---|
1 | pending | Request submitted, awaiting admin approval |
2 | approved | Approved; sent to Radarr/Sonarr for download |
3 | declined | Request was rejected by an admin |
4 | available | Media is available in Plex/Jellyfin |
5 | partially_available | Some seasons/episodes are available |
8 | failed | Download or processing error in Radarr/Sonarr |
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.
# 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)
/plugin marketplace add jmagar/claude-homelab
/plugin install overseerr-mcp @jmagar-claude-homelab
uv sync --dev
uv run overseerr-mcp-server
Alternative entrypoint:
uv run python -m overseerr_mcp
All credentials live in a single dotfile:
~/.config/overseerr-mcp/.env
Bootstrap it from the example:
just setup # mkdir -p ~/.config/overseerr-mcp && cp .env.example ~/.config/overseerr-mcp/.env
Then edit ~/.config/overseerr-mcp/.env and fill in OVERSEERR_URL and OVERSEERR_API_KEY.
See docs/ENV.md for the full variable reference including media service vars, Docker vars, and how each deployment mode loads the file.
| Variable | Required | Default | Description |
|---|---|---|---|
OVERSEERR_URL | yes | — | Base URL of your Overseerr instance (e.g. https://overseerr.example.com) |
OVERSEERR_API_KEY | yes | — | Overseerr API key (Settings → General → API Key) |
OVERSEERR_MCP_TRANSPORT | no | stdio | stdio for Claude Code plugin/uvx; http for Docker/standalone |
OVERSEERR_MCP_PORT | no | 9151 | Port for HTTP transport |
OVERSEERR_MCP_TOKEN | no | — | Bearer token for HTTP auth; generate with openssl rand -hex 32 |
OVERSEERR_MCP_NO_AUTH | no | false | Disable bearer auth on HTTP transport (only if network-level auth is in place) |
OVERSEERR_LOG_LEVEL | no | INFO | DEBUG, INFO, WARNING, or ERROR |
| Mode | When to use |
|---|---|
stdio | Claude Code plugin, uvx, local CLI — default |
http | Docker, standalone server, any HTTP MCP client |
For HTTP transport, the MCP endpoint is at /mcp. Requests must include Authorization: Bearer <OVERSEERR_MCP_TOKEN> unless OVERSEERR_MCP_NO_AUTH=true. The /health endpoint is always unauthenticated.
just gen-token # generates: openssl rand -hex 32
Set OVERSEERR_MCP_TOKEN in ~/.config/overseerr-mcp/.env.
All tools return an error string beginning with "Error:" when something goes wrong. Common errors:
| Error pattern | Cause |
|---|---|
Error: Overseerr API request failed (401) | OVERSEERR_API_KEY is invalid or missing |
Error: Overseerr API request failed (404) | TMDB ID does not exist in Overseerr |
Error: Overseerr API request failed (409) | Request already exists for this media |
Error: Failed to connect to Overseerr | OVERSEERR_URL is unreachable |
Error: Overseerr API client is not available | Server startup failed (check logs) |
No results found for query '...' | Search returned zero matches |
Always check whether the return value is a string before treating it as a dict or list.
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
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
| Plugin | Category | Description |
|---|---|---|
| homelab-core | core | Core agents, commands, skills, and setup/health workflows for homelab management. |
| unraid-mcp | infrastructure | Query, monitor, and manage Unraid servers: Docker, VMs, array, parity, and live telemetry. |
| unifi-mcp | infrastructure | Monitor and manage UniFi devices, clients, firewall rules, and network health. |
| gotify-mcp | utilities | Send and manage push notifications via a self-hosted Gotify server. |
| swag-mcp | infrastructure | Create, edit, and manage SWAG nginx reverse proxy configurations. |
| synapse-mcp | infrastructure | Docker management (Flux) and SSH remote operations (Scout) across homelab hosts. |
| arcane-mcp | infrastructure | Manage Docker environments, containers, images, volumes, networks, and GitOps via Arcane. |
| syslog-mcp | infrastructure | Receive, index, and search syslog streams from all homelab hosts via SQLite FTS5. |
| plugin-lab | dev-tools | Scaffold, review, align, and deploy homelab MCP plugins with agents and canonical templates. |
MIT
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.