Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,66 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [2.0.0] - 2026-02-18

### Added
- **Seerr Support**: Full compatibility with Seerr (Overseerr/Jellyseerr merger)
- API is 100% backward compatible
- No functional changes required
- **Dual Environment Variable Support**
- New `SEERR_URL` and `SEERR_API_KEY` environment variables (preferred)
- Legacy `OVERSEERR_URL` and `OVERSEERR_API_KEY` still supported
- `SEERR_*` variables take precedence when both are provided
- Deprecation warnings logged for `OVERSEERR_*` variables

### Changed
- **Branding Update**: Primary branding changed from Overseerr to Seerr
- Server name: `overseerr-mcp` → `seerr-mcp` (internal)
- Package name remains `@jhomen368/overseerr-mcp` for backward compatibility
- Docker image remains `ghcr.io/jhomen368/overseerr-mcp`
- **Documentation**: Updated README.md to reflect Seerr as primary, Overseerr as legacy
- All examples use `SEERR_*` environment variables
- Added migration notes for existing users
- **Logging**: Enhanced server startup messages to indicate Seerr/Overseerr compatibility
- Health check endpoint now includes compatibility list
- **Error Messages**: Updated to use "Seerr" terminology

### Deprecated
- `OVERSEERR_URL` and `OVERSEERR_API_KEY` environment variables
- Will be removed in v3.0.0 (planned for ~1 year from now)
- Use `SEERR_URL` and `SEERR_API_KEY` instead
- Deprecation warnings are non-intrusive (stderr only)

### Migration Guide
**For Existing Users:**
1. **No action required** - All OVERSEERR_* variables continue to work
2. **Recommended**: Update environment variables from `OVERSEERR_*` to `SEERR_*`
3. **Claude Desktop users**: Update `claude_desktop_config.json` to use `SEERR_*` variables
4. **Docker users**: Update environment variables in docker-compose.yml or docker run commands

**Example Migration:**
```json
// OLD (still works, but deprecated)
{
"env": {
"OVERSEERR_URL": "https://overseerr.example.com",
"OVERSEERR_API_KEY": "your-key"
}
}

// NEW (recommended)
{
"env": {
"SEERR_URL": "https://overseerr.example.com", // Works with both Seerr and Overseerr
"SEERR_API_KEY": "your-key"
}
}
```

**Breaking Changes:** None - 100% backward compatible

---

## [1.2.4] - 2026-01-12

### Fixed
Expand Down
12 changes: 6 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing to Overseerr MCP Server
# Contributing to Seerr MCP Server

Thank you for your interest in contributing to Overseerr MCP Server! This document provides guidelines for contributing to the project.
Thank you for your interest in contributing to Seerr MCP Server! This document provides guidelines for contributing to the project.

## Code of Conduct

Expand Down Expand Up @@ -47,7 +47,7 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme

- Node.js 18.0 or higher
- npm or yarn
- Access to an Overseerr instance for testing
- Access to a Seerr or Overseerr instance for testing

### Local Development

Expand All @@ -64,8 +64,8 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme

3. Create a `.env` file with your test credentials:
```env
OVERSEERR_URL=https://your-test-overseerr.com
OVERSEERR_API_KEY=your-api-key
SEERR_URL=https://your-test-seerr.com
SEERR_API_KEY=your-api-key
```

4. Build the project:
Expand Down Expand Up @@ -95,7 +95,7 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
Before submitting a pull request:

1. Build the project successfully
2. Test with a real Overseerr instance
2. Test with a real Seerr or Overseerr instance
3. Verify all existing functionality still works
4. Test your new features/fixes

Expand Down
5 changes: 3 additions & 2 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,9 @@ EXPOSE 8085

# Environment variables
# These MUST be provided at runtime:
# - OVERSEERR_URL: Your Overseerr instance URL (e.g., https://overseerr.example.com)
# - OVERSEERR_API_KEY: Your Overseerr API key
# - SEERR_URL or OVERSEERR_URL (legacy): Your Seerr/Overseerr instance URL
# - SEERR_API_KEY or OVERSEERR_API_KEY (legacy): Your API key
# Note: SEERR_* variables are preferred; OVERSEERR_* will show deprecation warnings
ENV HTTP_MODE=true \
PORT=8085 \
NODE_ENV=production
Expand Down
60 changes: 38 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Overseerr MCP Server
# Seerr MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![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)
[![Version](https://img.shields.io/badge/version-1.2.4-blue.svg)](https://github.com/jhomen368/overseerr-mcp)
[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/jhomen368/overseerr-mcp)
[![PayPal](https://img.shields.io/badge/Donate-PayPal-blue.svg)](https://www.paypal.com/donate?hosted_button_id=PBRD7FXKSKAD2)

> **A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server providing AI assistants with direct integration to [Overseerr](https://overseerr.dev/) for automated media discovery, requests, and management in your Plex ecosystem.**
> **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.**

## 🎯 Key Features

Expand Down Expand Up @@ -44,8 +44,8 @@
## 📋 Prerequisites

- **Node.js** 18.0 or higher
- **Overseerr instance** (self-hosted or managed)
- **Overseerr API key** (Settings → General in Overseerr)
- **Seerr or Overseerr instance** (self-hosted or managed)
- **Seerr/Overseerr API key** (Settings → General in your instance)

## 🚀 Quick Start

Expand All @@ -64,41 +64,52 @@ Add to your configuration file:
```json
{
"mcpServers": {
"overseerr": {
"seerr": {
"command": "npx",
"args": ["-y", "@jhomen368/overseerr-mcp"],
"env": {
"OVERSEERR_URL": "https://overseerr.example.com",
"OVERSEERR_API_KEY": "your-api-key-here"
"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:
> ```json
> {
> "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)

```bash
docker run -d \
--name overseerr-mcp \
--name seerr-mcp \
-p 8085:8085 \
-e OVERSEERR_URL=https://your-overseerr-instance.com \
-e OVERSEERR_API_KEY=your-api-key-here \
-e SEERR_URL=https://your-seerr-instance.com \
-e SEERR_API_KEY=your-api-key-here \
ghcr.io/jhomen368/overseerr-mcp:latest
```

**Docker Compose:**

```yaml
services:
overseerr-mcp:
seerr-mcp:
image: ghcr.io/jhomen368/overseerr-mcp:latest
container_name: overseerr-mcp
container_name: seerr-mcp
ports:
- "8085:8085"
environment:
- OVERSEERR_URL=https://your-overseerr-instance.com
- OVERSEERR_API_KEY=your-api-key-here
- SEERR_URL=https://your-seerr-instance.com
- SEERR_API_KEY=your-api-key-here
restart: unless-stopped
```

Expand Down Expand Up @@ -207,7 +218,7 @@ manage_media_requests({

Simply ask your AI assistant:

- "Search for Inception in Overseerr"
- "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"
Expand All @@ -219,8 +230,12 @@ Simply ask your AI assistant:
### Environment Variables

**Required:**
- `OVERSEERR_URL` - Your Overseerr instance URL
- `OVERSEERR_API_KEY` - API key from Overseerr Settings → General
- `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):**
```bash
Expand All @@ -243,20 +258,20 @@ PORT=8085 # HTTP server port
## 🔧 Troubleshooting

### Connection Issues
- Verify Overseerr URL is accessible
- Verify Seerr/Overseerr URL is accessible
- Check API key validity (Settings → General)
- Review firewall rules for remote access

### Docker Issues
```bash
# Check logs
docker logs overseerr-mcp
docker logs seerr-mcp

# Verify health
curl http://localhost:8085/health

# Restart container
docker restart overseerr-mcp
docker restart seerr-mcp
```

### Build Issues
Expand All @@ -280,7 +295,8 @@ MIT License - see [LICENSE](LICENSE) for details

## 🙏 Acknowledgments

- [Overseerr](https://overseerr.dev/) - Media request and discovery tool
- [Seerr](https://github.com/seerr) - Next-generation media request and discovery tool
- [Overseerr](https://overseerr.dev/) - Original media request tool for Plex
- [Model Context Protocol](https://modelcontextprotocol.io) - Open protocol for AI integrations
- [Anthropic](https://www.anthropic.com/) - Creators of the MCP standard

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 4 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@jhomen368/overseerr-mcp",
"version": "1.2.4",
"description": "Model Context Protocol (MCP) server for Overseerr - enables AI assistants to search, request, and manage media through your Overseerr instance",
"version": "2.0.0",
"description": "MCP server for Overseerr/Seerr media request automation",
"type": "module",
"author": "jhomen368",
"license": "MIT",
Expand All @@ -13,6 +13,8 @@
"mcp",
"model-context-protocol",
"overseerr",
"seerr",
"jellyseerr",
"plex",
"media",
"automation",
Expand Down
Loading