Back to Browse
Free
Server data from the Official MCP Registry
MCP server for Overseerr media requests and discovery.
About
MCP server for Overseerr media requests and discovery.
Security Report
10.0
Low Risk10.0Low RiskValid 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.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Base URL of your Overseerr instance, e.g. https://overseerr.example.com.
Environment variable: OVERSEERR_URL
Overseerr API key (Settings > General > API Key).Required
Environment variable: OVERSEERR_API_KEY
How to Install
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"
}
}
}Documentation
View on GitHubFrom the project's GitHub README.
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 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
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/Sonarr download state |
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.
| 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)
request_movie
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)
request_tv_show
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_failed_requests
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.
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. ThetmdbIdfield 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
mediaTypefield 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.
| 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.
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
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.
Key variables
| 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 |
Transport modes
| 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.
Authentication
just gen-token # generates: openssl rand -hex 32
Set OVERSEERR_MCP_TOKEN in ~/.config/overseerr-mcp/.env.
Error handling
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.
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
| 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. |
License
MIT
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
80.0K
Stars
3
Installs
6.5
Security
No ratings yet
Local
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
114
Stars
404
Installs
8.0
Security
4.8
Local
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
-
Stars
55
Installs
10.0
Security
5.0
Local
MarkItDown
Freeby Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
89.9K
Stars
15
Installs
6.0
Security
5.0
Local
mcp-creator-typescript
Freeby mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
-
Stars
14
Installs
10.0
Security
5.0
Local
FinAgent
Freeby mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.
-
Stars
13
Installs
10.0
Security
No ratings yet
Local