Seerr MCP Server

1# Seerr MCP Server
2 
3[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white)](https://github.com/jhomen368/overseerr-mcp/pkgs/container/overseerr-mcp)
5[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/jhomen368/overseerr-mcp)
6[![PayPal](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://www.paypal.com/donate?hosted_button_id=PBRD7FXKSKAD2)
7 
8> **A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for Overseerr and Seerr (the unified successor) that enables AI assistants to search, request, and manage media through the Model Context Protocol.**
9 
10## 🎯 Key Features
11 
12- **🚀 99% fewer API calls** for batch operations (150-300 → 1)
13- **⚡ 88% token reduction** with compact response formats  
14- **🎯 Batch Dedupe Mode** - Check 50-100 titles in one operation
15- **🔄 Smart Caching** - 70-85% API call reduction
16- **🛡️ Safety Features** - Multi-season confirmation, validation
17- **📦 4 Powerful Tools** - Consolidated from 8 for clarity
18 
19## 🔒 Security
20 
21- **🤖 Automated Security Scanning**
22  - Dependabot for dependency updates (weekly)
23  - CodeQL for code vulnerability analysis (PR + weekly)
24  - Trivy for Docker image scanning (CI only - blocks PRs if vulnerabilities found)
25  - CI validates everything during PR review, CD trusts CI and publishes
26- **🐳 Hardened Docker Images**
27  - Non-root user (mcpuser)
28  - Multi-stage builds
29  - Minimal Alpine base
30  - dumb-init process management
31- **✅ Input Validation**
32  - URL and API key format validation
33  - Fails fast with clear error messages
34 
35## 🛠️ Available Tools
36 
37| Tool | Purpose | Key Features |
38|------|---------|--------------|
39| **search_media** | Search & dedupe | Single/batch search, dedupe mode for 50-100 titles, franchise awareness |
40| **request_media** | Request movies/TV | Batch requests, season validation, multi-season confirmation, dry-run mode |
41| **manage_media_requests** | Manage requests | List/approve/decline/delete, filtering, summary statistics |
42| **get_media_details** | Get media info | Batch lookup, flexible detail levels (basic/standard/full) |
43 
44## 📋 Prerequisites
45 
46- **Node.js** 18.0 or higher
47- **Seerr or Overseerr instance** (self-hosted or managed)
48- **Seerr/Overseerr API key** (Settings → General in your instance)
49 
50## 🚀 Quick Start
51 
52### Option 1: NPM (Recommended)
53 
54```bash
55npm install -g @jhomen368/overseerr-mcp
56```
57 
58**Configure with Claude Desktop:**
59 
60Add to your configuration file:
61- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
62- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
63 
64```json
65{
66  "mcpServers": {
67    "seerr": {
68      "command": "npx",
69      "args": ["-y", "@jhomen368/overseerr-mcp"],
70      "env": {
71        "SEERR_URL": "https://seerr.example.com",
72        "SEERR_API_KEY": "your-api-key-here"
73      }
74    }
75  }
76}
77```
78 
79> **Legacy Overseerr Users:** If you're still using Overseerr (not Seerr), you can continue using the legacy variables:
80> ```json
81> {
82>   "env": {
83>     "OVERSEERR_URL": "https://overseerr.example.com",
84>     "OVERSEERR_API_KEY": "your-api-key-here"
85>   }
86> }
87> ```
88> *Both `OVERSEERR_*` and `SEERR_*` variables are supported for backward compatibility. Legacy variables will be removed in v3.0.0.*
89 
90### Option 2: Docker (Remote Access)
91 
92```bash
93docker run -d \
94  --name seerr-mcp \
95  -p 8085:8085 \
96  -e SEERR_URL=https://your-seerr-instance.com \
97  -e SEERR_API_KEY=your-api-key-here \
98  ghcr.io/jhomen368/overseerr-mcp:latest
99```
100 
101**Docker Compose:**
102 
103```yaml
104services:
105  seerr-mcp:
106    image: ghcr.io/jhomen368/overseerr-mcp:latest
107    container_name: seerr-mcp
108    ports:
109      - "8085:8085"
110    environment:
111      - SEERR_URL=https://your-seerr-instance.com
112      - SEERR_API_KEY=your-api-key-here
113    restart: unless-stopped
114```
115 
116**Test the server:**
117```bash
118curl http://localhost:8085/health
119```
120 
121**Connect MCP clients:**
122- **Transport**: Streamable HTTP (SSE)
123- **URL**: `http://localhost:8085/mcp`
124 
125### Option 3: From Source
126 
127```bash
128git clone https://github.com/jhomen368/overseerr-mcp.git
129cd overseerr-mcp
130npm install
131npm run build
132node build/index.js
133```
134 
135## 💡 Usage Examples
136 
137### Batch Dedupe Workflow (Perfect for Anime Seasons)
138 
139```typescript
140// Check 50-100 titles in ONE API call
141search_media({
142  dedupeMode: true,
143  titles: [
144    "Frieren: Beyond Journey's End",
145    "My Hero Academia Season 7",
146    "Demon Slayer Season 4",
147    // ... 47 more titles
148  ],
149  autoNormalize: true  // Strips "Season N", "Part N", etc.
150})
151```
152 
153**Response:**
154```json
155{
156  "summary": {
157    "total": 50,
158    "pass": 35,
159    "blocked": 15,
160    "passRate": "70%"
161  },
162  "results": [
163    { "title": "Frieren", "status": "pass", "id": 209867 },
164    { "title": "My Hero Academia S7", "status": "pass", "franchiseInfo": "S1-S6 in library" },
165    { "title": "Demon Slayer S4", "status": "blocked", "reason": "Already requested" }
166  ]
167}
168```
169 
170### Request Media with Validation
171 
172```typescript
173// Single movie request
174request_media({
175  mediaType: "movie",
176  mediaId: 438631
177})
178 
179// TV show with specific seasons
180request_media({
181  mediaType: "tv",
182  mediaId: 82856,
183  seasons: [1, 2]
184})
185 
186// All seasons (excludes season 0 by default)
187request_media({
188  mediaType: "tv",
189  mediaId: 82856,
190  seasons: "all"
191})
192```
193 
194### Manage Requests
195 
196```typescript
197// List with filters
198manage_media_requests({
199  action: "list",
200  filter: "pending",
201  take: 20
202})
203 
204// Batch approve
205manage_media_requests({
206  action: "approve",
207  requestIds: [123, 124, 125]
208})
209 
210// Get summary statistics
211manage_media_requests({
212  action: "list",
213  summary: true
214})
215```
216 
217### Natural Language Examples
218 
219Simply ask your AI assistant:
220 
221- "Search for Inception in Seerr"
222- "Check if these 50 anime titles have been requested"
223- "Request Breaking Bad all seasons"
224- "Show me all pending media requests"
225- "Approve request ID 123"
226- "Get details for TMDB ID 550"
227 
228## ⚙️ Configuration
229 
230### Environment Variables
231 
232**Required:**
233- `SEERR_URL` - Your Seerr/Overseerr instance URL
234- `SEERR_API_KEY` - API key from Settings → General
235 
236**Legacy (deprecated, will be removed in v3.0.0):**
237- `OVERSEERR_URL` - Use `SEERR_URL` instead
238- `OVERSEERR_API_KEY` - Use `SEERR_API_KEY` instead
239 
240**Optional (with defaults):**
241```bash
242CACHE_ENABLED=true                   # Enable caching
243CACHE_SEARCH_TTL=300000             # Search cache: 5 min
244CACHE_MEDIA_TTL=1800000             # Media cache: 30 min
245CACHE_REQUESTS_TTL=60000            # Request cache: 1 min
246CACHE_MAX_SIZE=1000                 # Max cache entries
247REQUIRE_MULTI_SEASON_CONFIRM=true   # Confirm >24 episodes
248HTTP_MODE=false                      # Enable HTTP transport
249PORT=8085                            # HTTP server port
250```
251 
252## 📚 Documentation
253 
254- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
255- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines
256- **[Overseerr API Docs](https://api-docs.overseerr.dev/)** - Official API reference
257 
258## 🔧 Troubleshooting
259 
260### Connection Issues
261- Verify Seerr/Overseerr URL is accessible
262- Check API key validity (Settings → General)
263- Review firewall rules for remote access
264 
265### Docker Issues
266```bash
267# Check logs
268docker logs seerr-mcp
269 
270# Verify health
271curl http://localhost:8085/health
272 
273# Restart container
274docker restart seerr-mcp
275```
276 
277### Build Issues
278```bash
279# Ensure Node.js 18+
280node --version
281 
282# Clean rebuild
283rm -rf node_modules build
284npm install
285npm run build
286```
287 
288## 🤝 Contributing
289 
290Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
291 
292## 📄 License
293 
294MIT License - see [LICENSE](LICENSE) for details
295 
296## 🙏 Acknowledgments
297 
298- [Seerr](https://github.com/seerr) - Next-generation media request and discovery tool
299- [Overseerr](https://overseerr.dev/) - Original media request tool for Plex
300- [Model Context Protocol](https://modelcontextprotocol.io) - Open protocol for AI integrations
301- [Anthropic](https://www.anthropic.com/) - Creators of the MCP standard
302 
303---
304 
305**Support this project:** [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://www.paypal.com/donate?hosted_button_id=PBRD7FXKSKAD2)
306