Skip to main content
Glama
Overseerr MCP Server

Overseerr MCP Server

by suckerfish

Overseerr MCP Server

MCP server for Overseerr media request management. Enables AI assistants to search for media, view requests, and manage media requests through the Model Context Protocol.

Features

  • Search media - Find movies and TV shows by title with availability status

  • Media status - Check if content is available, processing, or needs to be requested

  • View requests - List requests with user info, filter by approval status, availability status, or time period

  • User management - List users and view individual request histories

  • Request media - Submit new requests with per-season selection for TV shows

  • User correlation - Easily answer questions like "list all requests from the last week and who requested them"

Related MCP server: nas-mcp-server

Requirements

  • Python 3.10+

  • uv package manager

  • Overseerr instance with admin API key

Installation

docker pull ghcr.io/suckerfish/overseerr-mcp:latest

From source

git clone https://github.com/suckerfish/overseerr-mcp.git
cd overseerr-mcp

# Create virtual environment and install dependencies
uv venv && uv pip install -e .

Configuration

Copy .env.example to .env and configure:

OVERSEERR_URL=http://your-overseerr-ip:5055
OVERSEERR_API_KEY=your-admin-api-key-here

Important: Use the admin API key from Settings → General → API Key in Overseerr (not a user-level key).

Usage

Local (stdio transport)

uv run python -m src.server

HTTP transport (for Docker/remote)

uv run python -m src.server --transport streamable-http --host 0.0.0.0 --port 8080

Docker

Pre-built images are available for linux/amd64 and linux/arm64.

# Using docker compose (recommended)
docker compose up -d

# Or run directly
docker run -d \
  -e OVERSEERR_URL=http://your-overseerr:5055 \
  -e OVERSEERR_API_KEY=your-api-key \
  -p 8080:8080 \
  ghcr.io/suckerfish/overseerr-mcp:latest

MCP Tools

Tool

Description

search_media

Search for movies/TV shows by title. Returns TMDB IDs, ratings, and availability status.

get_media_status

Check detailed availability status for a specific TMDB ID. Shows request status, media availability, and season count for TV.

get_requests

List media requests with user info. Filter by status (pending/approved), media_status (available/processing/unavailable/failed), or days. Use show_all=true to get all matches instead of the default 20.

get_users

List all Overseerr users with request counts.

get_user_requests

Get requests for a specific user. Filter by media_status (processing/available/etc). Default 20 results, use show_all=true for all.

request_media

Request a movie or TV show. TV shows require season selection for multi-season shows.

health_check

Check Overseerr server connectivity and version.

Example Queries

Once connected to an MCP client, you can ask:

  • "Search for The Matrix" - shows availability status inline

  • "Is Breaking Bad available?" - checks media status

  • "List all requests from the last week and who requested them"

  • "Show me all pending requests"

  • "What requests are still processing?" - filters by media availability

  • "What has user ID 5 requested?"

  • "Request the movie The Matrix"

  • "Request seasons 1-3 of Breaking Bad" - per-season TV requests

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "overseerr": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/path/to/plexrequest_mcp"
    }
  }
}

HTTP/Docker

{
  "mcpServers": {
    "overseerr": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

License

MIT

Available Tools

12 tools
add_issue_commentA

Add a comment to an issue.

Args: issue_id: The issue ID message: The comment text

Returns: The created comment

Inputs: message (required), issue_id (required). Returns: object

get_issueA

Get a single issue with its comments.

Args: issue_id: The issue ID

Returns: Issue details including all comments

Inputs: issue_id (required). Returns: object

get_issuesA

Get Overseerr issues (reports of problems with media).

Args: filter: "all", "open", or "resolved" (defaults to open) limit: Maximum number of issues to return (default 20) sort: "added" or "modified" (default added)

Returns: List of issues with type, status, reporter, and associated media

Inputs: sort, limit, filter. Returns: object

get_media_statusA

Check the availability status of a movie or TV show.

Use search_media first to find the TMDB ID, then check its detailed status. Returns whether media is available, being processed, or needs to be requested.

Args: tmdb_id: TMDB ID of the movie or TV show (from search results) media_type: "movie" or "tv"

Returns: Status information including: - status: Numeric status code (1=Unknown, 2=Requested, 3=Processing, 4=Partially Available, 5=Available) - status_text: Human-readable status like "Available" or "Processing" - has_request: Whether any request exists for this media - request_status: Status of existing request ("Pending", "Approved", "Declined") - seasons_count: (TV only) Total number of seasons

Inputs: tmdb_id (required), media_type (required). Returns: object

get_requestsA

Get media requests with user information.

Lists all requests showing who requested what and when. Perfect for queries like "list all requests from the last week and who requested them".

Args: status: Filter by request approval status - "pending" or "approved" media_status: Filter by availability - "available", "processing", "unavailable", or "failed" days: Optional - only show requests from the last N days limit: Maximum number of requests to return (default 20) show_all: Set to true to return all matching requests (ignores limit)

Returns: List of requests with titles, requesters, request status, and media availability

Inputs: days, limit, status, show_all, +1 more. Returns: object

get_user_requestsA

Get all requests made by a specific user.

Shows all media requests from a particular user. Get the user_id from the get_users tool.

Args: user_id: The Overseerr user ID media_status: Filter by availability - "processing", "available", or "partially_available" limit: Maximum number of requests to return (default 20) show_all: Set to true to return all matching requests (ignores limit)

Returns: User info and their request history filtered by media status

Inputs: user_id (required), limit, show_all, media_status. Returns: object

get_usersA

Get all Overseerr users.

Lists all users with their IDs and request counts. Use the user ID to get a specific user's requests.

Returns: List of users with IDs, names, and request counts

Inputs: no named parameters. Returns: object

health_checkA

Check Overseerr server status and connectivity.

Verifies the MCP server can connect to Overseerr.

Returns: Server status and version information

Inputs: no named parameters. Returns: object

request_mediaA

Request a movie or TV show to be added to Plex.

Use search_media first to find the TMDB ID for the content you want.

For TV shows with multiple seasons, you must specify which seasons to request. Single-season shows are auto-selected.

Args: tmdb_id: TMDB ID of the movie or TV show (from search results) media_type: "movie" or "tv" seasons: For TV shows - comma-separated season numbers (e.g., "1,2,3") or "all"

Returns: Request confirmation with title, status, and request ID

Inputs: tmdb_id (required), media_type (required), seasons. Returns: object

search_libraryA

Search your Plex library for movies and TV shows you already have.

Use this when a user asks what's in their library or wants to find content they already own. This searches by title substring within Plex, so "dracula" will match "Bram Stoker's Dracula".

To search for new content to request, use search_media instead.

Args: query: Title to search for (substring match) media_type: Optional filter - "movie" or "tv"

Returns: List of matching items from your Plex library with title, year, rating, and type

Inputs: query (required), media_type. Returns: object

search_mediaA

Search for movies and TV shows in Overseerr.

This searches TMDB (external database), not your Plex library. To search content you already own, use search_library instead.

Use this to find media by title before making a request. Returns TMDB IDs needed for requesting media.

Args: query: Search term (movie or TV show title) media_type: Optional filter - "movie" or "tv"

Returns: List of matching movies/TV shows with TMDB IDs, titles, years, ratings, and availability status

Inputs: query (required), media_type. Returns: object

update_issue_statusA

Update an issue's status (open or resolve it).

Args: issue_id: The issue ID status: "open" or "resolved"

Returns: Updated issue details

Inputs: status (required), issue_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have clear distinct purposes, but get_requests and get_user_requests both return request lists, and search_media and get_media_status both provide availability info. Descriptions explicitly call out the differences, avoiding major confusion.

    Naming Consistency4/5

    Tools mostly follow verb_noun snake_case (get_, search_, request_, update_, add_), but health_check breaks the pattern and singular/plural nouns vary (e.g., get_users vs get_issue). Overall consistent and readable.

    Tool Count5/5

    12 tools is well-scoped for an Overseerr server, covering users, media search, library search, request management, issue tracking, and health check without excessive overlap.

    Completeness3/5

    Core operations like search, request creation, status checking, and issue management are present, but the set lacks the ability to approve/deny requests—an essential Overseerr workflow. User management is also limited to listing, not editing roles or permissions.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      FastMCP server to interact with the Overseerr API for movie and TV show requests management, enabling users to request media, search, and manage libraries via natural language.
      8
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing a media server stack (Plex, Radarr, Overseerr, Bazarr, Prowlarr, Trakt.tv) using natural language to browse, request, and discover content.
      12
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      A Model Context Protocol server that exposes Sonarr, Radarr, Lidarr, and Jellyfin to any MCP client through a curated tool layer for LLM consumption.
      38 PyPI
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server for Overseerr that enables searching, requesting, and managing media (movies and TV shows) through natural language, with integration to Radarr/Sonarr for automated downloads.
      -