FastMCP server for Overseerr

FastMCP server for Seerr

FastMCP server to interact with the Seerr API for movie and TV show requests management, built using the fastmcp library.

Project Repository: https://github.com/ptbsare/seerr-mcp-server

Components

Tools

The server implements the following tools to interact with Seerr:

• seerr_status: Get the status of the Seerr server.
• seerr_movie_requests: Get a paginated list of movie requests. Accepts optional status, start_date (YYYY-MM-DDTHH:MM:SS.mmmZ format), take (default 7), and skip (default 0).
• seerr_tv_requests: Get a paginated list of TV show requests. Accepts optional status, start_date (YYYY-MM-DDTHH:MM:SS.mmmZ format), take (default 7), and skip (default 0).
• seerr_request_movie_to_library: Submit a movie request using its TMDB ID to a specific library, on behalf of a specific user. Requires tmdb_id, library_name, and user_display_name. Available library names and user display names (unique ones only) are fetched at server startup and included in the tool's argument descriptions.
• seerr_request_tv_to_library: Submit a TV show request using its TMDB ID to a specific library, on behalf of a specific user. Requires tmdb_id, library_name, and user_display_name. Optionally accepts seasons (list of integers). Available library names and user display names (unique ones only) are fetched at server startup and included in the tool's argument descriptions.
• seerr_search_media: Search for movies and TV shows available on Seerr. Accepts query and optional page (default 1).
• seerr_get_available_libraries: Get the configured Sonarr (TV) and Radarr (Movie) server IDs and names from Seerr.
• seerr_get_users: Get a list of all users configured in Seerr, including their ID, username, email, displayName, etc.

Example prompts

It's good to first instruct your AI assistant (e.g., Claude) to use the Seerr tools. Then it can call the appropriate tool when needed.

Try prompts like these:

• Get the status of our Seerr server.
• Show me the first 5 movie requests that are currently pending.
• List all TV show requests from 2024-01-01 that are now available.
• What movies have been requested but are not available yet?
• What TV shows have recently become available in our library?
• Search for the movie "Dune: Part Two" on Seerr.
• What movie and TV libraries are configured in Seerr?
• List all users in Seerr.
• Request the movie with TMDB ID 693134 for the user 'John Doe' in the 'Movies HD' library. (Uses user_display_name='John Doe', library_name='Movies HD')
• Request seasons 1 and 2 for the TV show with TMDB ID 1396 for user 'Jane Smith' in the 'TV Shows 4K' library. (Uses user_display_name='Jane Smith')

Quickstart

Prerequisites

• uv (installation instructions: https://github.com/astral-sh/uv)
• An Seerr instance running.
• API Key from your Seerr instance (Settings → API Keys).

Run with uvx (Recommended - No Installation Required)

You can run the server directly from the git repository using uvx — no clone or install needed:

uvx --from git+https://github.com/ptbsare/seerr-mcp-server.git seerr-mcp-server

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "seerr-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ptbsare/seerr-mcp-server.git",
        "seerr-mcp-server"
      ],
      "env": {
        "SEERR_API_KEY": "<your_api_key_here>",
        "SEERR_URL": "<your_seerr_url>"
      }
    }
  }
}

Replace <your_api_key_here> and <your_seerr_url> with your actual Seerr API key and URL.

Environment Variables

The following environment variables are required:

• SEERR_API_KEY: Your Seerr API key (found in Seerr Settings → API Keys)
• SEERR_URL: The URL of your Seerr instance (e.g., http://localhost:5055)

For clients like Claude Desktop, add these to the env field as shown above. For local use, you can export them or use a .env file:

SEERR_API_KEY=your_api_key_here
SEERR_URL=http://localhost:5055

Local Development Installation

If you prefer to install locally for development:

git clone https://github.com/ptbsare/seerr-mcp-server.git
cd seerr-mcp-server
uv venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
uv pip install -e .

Development

Setup

Follow the installation steps using uv pip install -e . for an editable install.

Dependencies

Install or sync dependencies using uv:

uv sync
# or
uv pip install -e .

Debugging

Since MCP servers run over stdio, debugging can be challenging.

• MCP Inspector: The MCP Inspector is highly recommended.

  Launch it pointing to your server script:

  # Using uvx (no local installation needed)
  npx @modelcontextprotocol/inspector uvx --from git+https://github.com/ptbsare/seerr-mcp-server.git seerr-mcp-server
  
  # Or using uv run (from local project directory)
  npx @modelcontextprotocol/inspector uv run seerr-mcp-server
  

  Access the URL provided by the Inspector in your browser.

• Logging: The server logs basic information to stdout/stderr. Check the terminal where you ran uv run seerr-mcp-server. For clients like Claude Desktop, check the client's log files (e.g., ~/Library/Logs/Claude/mcp-server-seerr-mcp.log on macOS, but the name might vary based on your config).

License

MIT