jhomen368/overseerr-mcp

License: MIT Docker Version PayPal

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:

{
  "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:

curl http://localhost:8085/health

Connect MCP clients:

• Transport: Streamable HTTP (SSE)
• 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:

{
  "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):

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