Skip to main content
Glama
Sign In
Seerr MCP Server

Seerr MCP Server

by VicePrez
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Hybrid

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

    A3.8/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool maps to a distinct action (list services, search, request, manage requests, details, service config), but the pairs get_services/get_service_details and search_media/get_media_details have overlapping-sounding names that require reading descriptions to separate. The descriptions do clarify the boundary (list vs. config detail; quick status vs. full detail), so misselection risk is low but non-zero.

    Naming Consistency4/5

    All names use snake_case with a verb_noun pattern (get_services, search_media, request_media, manage_media_requests), which is highly predictable. Minor inconsistency in granularity between get_services (plural list) and get_service_details (singular detail), but the convention holds.

    Tool Count5/5

    Six tools is a tight, well-scoped surface for a Seerr/Radarr/Sonarr request-proxy server, with no redundant or filler tools. Each tool covers a distinct stage of the discover→request→manage→inspect workflow.

    Completeness4/5

    The core lifecycle is covered: service discovery, media search with actionable statuses, request creation with confirmation rules, request management (get/list/approve/decline/delete), and detail inspection. Gaps exist around library-side operations (deleting media from Radarr/Sonarr) and user/quota or settings management, but agents can work around these.

    Resources

    Related MCP Connectors

    Related MCP Servers