Seerr MCP Server

![License: MIT](https://opensource.org/licenses/MIT) ![Docker](https://github.com/jhomen368/overseerr-mcp/pkgs/container/overseerr-mcp) ![Version](https://github.com/jhomen368/overseerr-mcp) ![PayPal](https://www.paypal.com/donate?hosted_button_id=PBRD7FXKSKAD2)

A Model Context Protocol (MCP) server for Overseerr and Seerr (the unified successor) that enables AI assistants to search, request, and manage media through the Model Context Protocol.

🎯 Key Features

🚀 99% fewer API calls for batch operations (150-300 → 1)
⚡ 88% token reduction with compact response formats
🎯 Batch Dedupe Mode - Check 50-100 titles in one operation
🔄 Smart Caching - 70-85% API call reduction
🛡️ Safety Features - Multi-season confirmation, validation
📦 6 Tools - Search, request, and manage media | Discover Radarr/Sonarr server configurations

🔒 Security

🤖 Automated Security Scanning
Dependabot for dependency updates (weekly)
CodeQL for code vulnerability analysis (PR + weekly)
Trivy for Docker image scanning (CI only - blocks PRs if vulnerabilities found)
CI validates everything during PR review, CD trusts CI and publishes
🐳 Hardened Docker Images
Non-root user (mcpuser)
Multi-stage builds
Minimal Alpine base
dumb-init process management
✅ Input Validation
URL and API key format validation
Fails fast with clear error messages

🛠️ Available Tools

| Tool | Purpose | Key Features | |------|---------|--------------| | search_media | Search & dedupe | Single/batch search, dedupe mode for 50-100 titles, franchise awareness | | request_media | Request movies/TV | Batch requests, season validation, multi-season confirmation, dry-run mode | | manage_media_requests | Manage requests | List/approve/decline/delete, filtering, summary statistics | | get_media_details | Get media info | Batch lookup, flexible detail levels (basic/standard/full) | | get_services | List Radarr/Sonarr servers | Discover server IDs, active defaults, 4K status | | get_service_details | Get server config | Quality profiles, root folders, tags per server |

📋 Prerequisites

Node.js 18.0 or higher
Seerr or Overseerr instance (self-hosted or managed)
Seerr/Overseerr API key (Settings → General in your instance)

🚀 Quick Start

Option 1: NPM (Recommended)

npm install -g @jhomen368/overseerr-mcp

Configure with Claude Desktop:

Add to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Legacy Overseerr Users: If you're still using Overseerr (not Seerr), you can continue using the legacy variables: ``json { "env": { "OVERSEERR_URL": "https://overseerr.example.com", "OVERSEERR_API_KEY": "your-api-key-here" } } ` Both OVERSEERR_ and SEERR_` variables are supported for backward compatibility. Legacy variables will be removed in v3.0.0.

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:

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: ``bash curl http://localhost:8085/health ``

Connect MCP clients:

Transport: Streamable HTTP
URL: 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

💡 Usage Examples

Batch Dedupe Workflow (Perfect for Anime Seasons)

// Check 50-100 titles in ONE API call
search_media({
  dedupeMode: true,
  titles: [
    "Frieren: Beyond Journey's End",
    "My Hero Academia Season 7",
    "Demon Slayer Season 4",
    // ... 47 more titles
  ],
  autoNormalize: true  // Strips "Season N", "Part N", etc.
})

Response: ``json { "summary": { "total": 50, "pass": 35, "blocked": 15, "passRate": "70%" }, "results": [ { "title": "Frieren", "status": "pass", "id": 209867 }, { "title": "My Hero Academia S7", "status": "pass", "franchiseInfo": "S1-S6 in library" }, { "title": "Demon Slayer S4", "status": "blocked", "reason": "Already requested" } ] } ``

Request Media with Validation

// Single movie request
request_media({
  mediaType: "movie",
  mediaId: 438631
})

// TV show with specific seasons
request_media({
  mediaType: "tv",
  mediaId: 82856,
  seasons: [1, 2]
})

// All seasons (excludes season 0 by default)
request_media({
  mediaType: "tv",
  mediaId: 82856,
  seasons: "all"
})

Manage Requests

// List with filters
manage_media_requests({
  action: "list",
  filter: "pending",
  take: 20
})

// Batch approve
manage_media_requests({
  action: "approve",
  requestIds: [123, 124, 125]
})

// Get summary statistics
manage_media_requests({
  action: "list",
  summary: true
})

Service Discovery

// List all configured servers (Radarr + Sonarr)
get_services({})

// List only Radarr servers
get_services({ serviceType: "radarr" })

// Get quality profiles, root folders, and tags for a server
get_service_details({
  serviceType: "radarr",
  serverId: 0
})

// Use discovered values when requesting media
request_media({
  mediaType: "movie",
  mediaId: 438631,
  serverId: 0,
  profileId: 13,
  rootFolder: "/data/media/movies"
})

Natural Language Examples

Simply ask your AI assistant:

"Search for Inception in Seerr"
"Check if these 50 anime titles have been requested"
"Request Breaking Bad all seasons"
"Show me all pending media requests"
"Approve request ID 123"
"Get details for TMDB ID 550"
"What Radarr servers are configured?"
"Show me the quality profiles for my Sonarr server"

⚙️ Configuration

Environment Variables

Required:

SEERR_URL - Your Seerr/Overseerr instance URL
SEERR_API_KEY - API key from Settings → General

Legacy (deprecated, will be removed in v3.0.0):

OVERSEERR_URL - Use SEERR_URL instead
OVERSEERR_API_KEY - Use SEERR_API_KEY instead

Optional (with defaults): ``bash CACHE_ENABLED=true # Enable caching CACHE_SEARCH_TTL=300000 # Search cache: 5 min CACHE_MEDIA_TTL=1800000 # Media cache: 30 min CACHE_REQUESTS_TTL=60000 # Request cache: 1 min CACHE_MAX_SIZE=1000 # Max cache entries CACHE_SERVICES_TTL=600000 # Services cache: 10 min CACHE_SERVICEDETAILS_TTL=600000 # Service details cache: 10 min REQUIRE_MULTI_SEASON_CONFIRM=true # Confirm >24 episodes HTTP_MODE=false # Enable HTTP transport PORT=8085 # HTTP server port ``

📚 Documentation

CHANGELOG.md - Version history and release notes
CONTRIBUTING.md - Contribution guidelines
Overseerr API Docs - Official API reference

🔧 Troubleshooting

Connection Issues

Verify Seerr/Overseerr URL is accessible
Check API key validity (Settings → General)
Review firewall rules for remote access

Docker Issues

# Check logs
docker logs seerr-mcp

# Verify health
curl http://localhost:8085/health

# Restart container
docker restart seerr-mcp

Build Issues

# Ensure Node.js 18+
node --version

# Clean rebuild
rm -rf node_modules build
npm install
npm run build

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details

🙏 Acknowledgments

Seerr - Next-generation media request and discovery tool
Overseerr - Original media request tool for Plex
Model Context Protocol - Open protocol for AI integrations
Anthropic - Creators of the MCP standard

---

Support this project: ![PayPal](https://www.paypal.com/donate?hosted_button_id=PBRD7FXKSKAD2)

overseerr-mcp