A
security-
licenseA
qualityAniList MCP server for accessing AniList API data
Last updated -
118
44
181
58
MIT License
This server enables AI assistants to interact with Overseerr for automated media discovery, requests, and management in your Plex ecosystem.
Core Capabilities:
Search & Discovery: Unified search for movies, TV shows, and people with pagination and language support. Features highly efficient batch search and dedupe modes to check 50-100 titles at once with 99% fewer API calls.
Media Requests: Request movies or TV shows by TMDB ID with optional 4K quality, custom servers, and quality profiles. TV show requests support specific seasons or all seasons with smart confirmation for large requests (>24 episodes).
Request Management: List, approve, decline, and delete media requests with filtering by status (pending, approved, available, etc.). Permission-aware operations ensure users see only their requests while admins see all.
Detail Lookup: Retrieve flexible information about movies and TV shows using TMDB IDs with basic, standard, or full response levels including ratings, genres, runtime, and seasons.
Status Checking: Search by title to verify if media has been requested and check current status and availability.
Batch Operations: Efficient batch processing with 88% token reduction and smart caching that reduces API calls by 70-85%, optimized for workflows like anime season checks.
Smart Validation: Automatic pre-request checks, season validation, and confirmation prompts to prevent accidental bulk downloads.
Provides integration with Overseerr for automated media discovery, requests, and management in a Plex ecosystem. Enables searching for movies and TV shows, requesting media (with options for specific seasons and 4K), checking request status, managing approvals and declines, and viewing detailed media information from TMDB.
Overseerr MCP Server
A
✨ What's New in v1.2.3
Enhanced Security Features
Added automated security workflows (Dependabot, CodeQL, Trivy)
Docker image hardening with non-root user and minimal base image
Input validation for URLs and API keys
See CHANGELOG.md for full version history
🎯 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
📦 4 Powerful Tools - Consolidated from 8 for clarity
🔒 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) |
📋 Prerequisites
Node.js 18.0 or higher
Overseerr instance (self-hosted or managed)
Overseerr API key (Settings → General in Overseerr)
🚀 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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"overseerr": {
"command": "npx",
"args": ["-y", "@jhomen368/overseerr-mcp"],
"env": {
"OVERSEERR_URL": "https://overseerr.example.com",
"OVERSEERR_API_KEY": "your-api-key-here"
}
}
}
}
Option 2: Docker (Remote Access)
docker run -d \
--name overseerr-mcp \
-p 8085:8085 \
-e OVERSEERR_URL=https://your-overseerr-instance.com \
-e OVERSEERR_API_KEY=your-api-key-here \
ghcr.io/jhomen368/overseerr-mcp:latest
Docker Compose:
services:
overseerr-mcp:
image: ghcr.io/jhomen368/overseerr-mcp:latest
container_name: overseerr-mcp
ports:
- "8085:8085"
environment:
- OVERSEERR_URL=https://your-overseerr-instance.com
- OVERSEERR_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
})
Natural Language Examples
Simply ask your AI assistant:
"Search for Inception in Overseerr"
"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"
⚙️ Configuration
Environment Variables
Required:
OVERSEERR_URL- Your Overseerr instance URLOVERSEERR_API_KEY- API key from Overseerr Settings → General
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
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 Overseerr URL is accessible
Check API key validity (Settings → General)
Review firewall rules for remote access
Docker Issues
# Check logs
docker logs overseerr-mcp
# Verify health
curl http://localhost:8085/health
# Restart container
docker restart overseerr-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
Overseerr - Media request and discovery tool
Model Context Protocol - Open protocol for AI integrations
Anthropic - Creators of the MCP standard
Support this project: