Skip to main content
Glama
Sign In
Overseerr MCP Server

Overseerr MCP Server

by jhomen368
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
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

Available Tools

6 tools
get_media_detailsB

Get media details. Single/batch with level control (basic/standard/full). Media/season status: 1=UNKNOWN, 2=PENDING, 3=PROCESSING, 4=PARTIALLY_AVAILABLE, 5=AVAILABLE, 7=DELETED (Seerr). Code 6 is BLOCKLISTED in Seerr or DELETED in legacy Overseerr. Request statuses use a separate enum.

Inputs: items, level, fields, format, +3 more.

get_service_detailsB

Get quality profiles, root folders, tags, and language profiles (Sonarr) for a Radarr/Sonarr server.

Inputs: serviceType (required), serverId.

get_servicesA

List configured Radarr/Sonarr servers. Returns ID, name, isDefault, 4K status, active defaults (directory, profile, tags).

Inputs: serviceType.

manage_media_requestsB

Manage requests: get/list/approve/decline/delete. Supports filters and batching. Filters: all|pending|approved|available|processing|unavailable|failed

Inputs: action (required), skip, sort, take, +5 more.

request_mediaA

Request media with auto-confirm for TV ≤24 eps. Single/batch with validation. Confirm: Movies auto | TV ≤24 eps auto | TV >24 eps needs confirmed:true TV needs seasons (array or "all"). "all"=no specials; [0,1,2]=with specials

Inputs: is4k, items, dryRun, mediaId, +7 more.

search_mediaA

Search movies/TV with single/batch/dedupe modes. Dedupe returns actionable status for batch processing. Status: NOT_FOUND | ALREADY_AVAILABLE | ALREADY_REQUESTED | SEASON_AVAILABLE | SEASON_REQUESTED | AVAILABLE_FOR_REQUEST

Inputs: page, limit, query, format, +9 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: service configuration details, service listing, request management, media search, media request submission, and media status retrieval. No two tools have overlapping purposes; an agent can confidently select the correct tool for a given task.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., get_service_details, manage_media_requests, search_media, request_media). The naming is uniform and predictable, making it easy to infer functionality from the name alone.

    Tool Count5/5

    With 6 tools, the server is well-scoped for its purpose of managing media requests on Overseerr. Each tool serves a distinct function, and the count is neither too sparse nor bloated, providing a focused yet complete surface.

    Completeness5/5

    The tool set covers the full media request workflow: searching for media, requesting media, managing requests (get/list/approve/decline/delete), and retrieving detailed status for both services and media. No obvious gaps exist for the stated domain, and the inclusion of batch operations and status enums enhances capability.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches