Skip to main content
Glama
jhomen368

Overseerr MCP Server

by jhomen368
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

Seerr MCP Server

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

Related MCP server: Overseerr MCP Server

🔒 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

  • 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

🔧 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

Support this project: PayPal

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
2wRelease cycle
16Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jhomen368/overseerr-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server