# 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](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](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:

```bash
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`:

```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:

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

### Local Development Installation

If you prefer to install locally for development:

```bash
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`:

```bash
uv sync
# or
uv pip install -e .
```

### Debugging

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

-   **MCP Inspector:** The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is highly recommended.

    Launch it pointing to your server script:

    ```bash
    # 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