Seerr MCP Server

How to use

You interact with the MCP server through clients that speak the Model Context Protocol. Start by running the MCP server locally or on your preferred host, then connect your MCP client to the server using the provided transport. Most common workflows involve batch deduplicating media titles, requesting media (movies or TV shows), managing existing requests, and querying detailed media information. Use the batch and validation features to optimize large title lists and ensure requested seasons or episodes exist in your library.

How to install

Prerequisites you need before installing include Node.js version 18 or higher. You should also have access to a Seerr or Overseerr instance and a valid API key.

Installation and startup options are shown below. Choose the method you prefer and follow the steps exactly as written.

Option 1: NPM (Recommended)

npm install -g @jhomen368/overseerr-mcp
```

Configure with Claude Desktop by adding this MCP server entry to your configuration:

```json
{
  "mcpServers": {
    "seerr": {
      "command": "npx",
      "args": ["-y", "@jhomen368/overseerr-mcp"],
      "env": {
        "SEERR_URL": "https://seerr.example.com",
        "SEERR_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Docker (Remote Access)

docker run -d \
  --name seerr-mcp \
  -p 8085:8085 \
  -e SEERR_URL=https://your-seerr-instance.com \
  -e SEERR_API_KEY=your-api-key-here \
  ghcr.io/jhomen368/overseerr-mcp:latest
```

Docker Compose:

```yaml
services:
  seerr-mcp:
    image: ghcr.io/jhomen368/overseerr-mcp:latest
    container_name: seerr-mcp
    ports:
      - "8085:8085"
    environment:
      - SEERR_URL=https://your-seerr-instance.com
      - SEERR_API_KEY=your-api-key-here
    restart: unless-stopped
```

Test the server with the health endpoint and connect with the MCP client:

```bash
curl http://localhost:8085/health
```

Connect MCP clients using Streamable HTTP (SSE) transport at:

```
http://localhost:8085/mcp

Option 3: From Source

git clone https://github.com/jhomen368/overseerr-mcp.git
cd overseerr-mcp
npm install
npm run build
node build/index.js
```

This runs the MCP server from the source tree and builds the project before starting.

Additional sections

When configuring clients, use the provided HTTP transport URL or the local stdio command to connect to the MCP server. The HTTP transport uses a REST-like streamable interface at the /mcp endpoint, while the stdio transport runs a local process that your client can communicate with via the accepted protocol. Ensure your Seerr/Overseerr instance URL and API key are valid and kept secure.

Configuration and security

The server supports environment-based configuration, caching, and input validation to help you safely scale batch operations. For security, provide your Seerr/Overseerr URL and API key, enable caching with appropriate TTLs, and validate input to fail fast with clear error messages.

Troubleshooting

If you encounter connection issues, verify the Seerr/Overseerr URL is reachable and the API key is correct. Check firewall rules to allow remote access if you use the HTTP transport. For Docker, inspect logs and health endpoints, and restart the container if needed.

Notes

Legacy environment variables for Overseerr remain supported for backward compatibility, but new deployments should use the Seerr variables. Legacy variables will be removed in a future major release.

search_media

Search and deduplicate media titles with batch support, including a dedupe mode for large lists and franchise awareness.

request_media

Submit media requests with batch capability, season validation, multi-season confirmation, and a dry-run option.

manage_media_requests

List, approve, decline, or delete requests, with filtering and summary statistics.

get_media_details

Lookup media details in batches with adjustable detail levels (basic/standard/full).