Overseerr MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with direct integration to Overseerr, enabling automated media discovery, requests, and management for your Plex ecosystem.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables seamless integration between AI applications and external data sources. This server implements MCP to give AI assistants like Claude the ability to interact with your Overseerr instance.

Features

This server provides the following tools for interacting with your Overseerr instance:

Available Tools

1. search_media - Search for movies, TV shows, or people in Overseerr

   • Returns search results with media details including title, overview, release date, and rating

2. request_media - Request a movie or TV show

   • For TV shows, you can request specific seasons or all seasons
   • Supports 4K requests
   • Optional server, profile, and root folder configuration

3. get_request - Get details of a specific media request by ID

   • View request status, media status, requester, and timestamps

4. list_requests - List media requests with optional filtering

   • Filter by status (pending, approved, available, etc.)
   • Pagination support
   • Sort by added or modified date

5. update_request_status - Approve or decline media requests

   • Requires MANAGE_REQUESTS permission or ADMIN

6. get_media_details - Get detailed information about a movie or TV show

   • Fetches comprehensive TMDB data

7. delete_request - Delete a media request

   • Users can delete their own pending requests

8. check_request_status_by_title - Search for media by title and check request status

   • Returns all matching titles with request information
   • Shows request status (pending, approved, declined)
   • Displays media availability (pending, processing, available, etc.)
   • Perfect for checking if a title has already been requested before making a new request

Prerequisites

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

Configuration

Local Development (stdio mode)

Configure the server with environment variables:

• OVERSEERR_URL: Your Overseerr instance URL (e.g., https://overseerr.example.com)
• OVERSEERR_API_KEY: Your API key from Overseerr Settings → General

Docker/HTTP Mode (Streamable HTTP with SSE)

When running in Docker, HTTP transport with Server-Sent Events (SSE) is enabled by default. The following environment variables are required:

• OVERSEERR_URL: Your Overseerr instance URL
• OVERSEERR_API_KEY: Your Overseerr API key

The Docker image has these defaults (no need to override unless you want to change them):

• HTTP_MODE: true (HTTP transport enabled)
• PORT: 8085 (MCP server port)

Installation

NPM Installation

npm install -g @jhomen368/overseerr-mcp

From Source

git clone https://github.com/jhomen368/overseerr-mcp.git
cd overseerr-mcp
npm install
npm run build

Docker Build

Build the Docker image locally:

docker build -t overseerr-mcp .

Or pull from GitHub Container Registry:

docker pull ghcr.io/jhomen368/overseerr-mcp:latest

Docker Usage

Running with Docker

Basic Docker Run

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

Using Environment File

Create a .env file:

OVERSEERR_URL=https://your-overseerr-instance.com
OVERSEERR_API_KEY=your-api-key-here

Then run:

docker run -d \
  --name overseerr-mcp \
  -p 8085:8085 \
  --env-file .env \
  ghcr.io/jhomen368/overseerr-mcp:latest

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

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
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8085/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Start the service:

docker-compose up -d

HTTP Endpoints

When running in HTTP mode with streamable transport, the server exposes:

POST /mcp

The main MCP endpoint using Server-Sent Events for streaming communication. This is the endpoint you'll configure in your MCP client to connect to the server.

GET /health

Health check endpoint that returns server status:

curl http://localhost:8085/health

Response:

{
  "status": "ok",
  "service": "overseerr-mcp"
}

Verifying the Server

Check if the server is running:

# Check health endpoint
curl http://localhost:8085/health

# Check container logs
docker logs overseerr-mcp

# Check container status
docker ps | grep overseerr-mcp

Connecting MCP Clients

To connect an MCP client to the HTTP server, configure it with:

• Transport: Streamable HTTP (via SSE)
• URL: http://localhost:8085/mcp (or your server's address)
• Method: POST

The server uses Server-Sent Events (SSE) as the underlying mechanism for streamable HTTP transport, enabling efficient bidirectional communication.

Configuring with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %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"
      }
    }
  }
}

Other MCP Clients

For clients supporting streamable HTTP transport, configure with:

• URL: http://localhost:8085/mcp
• Transport: Streamable HTTP (SSE)
• Method: POST

Then start the server in HTTP mode using Docker (see Docker Usage section).

Usage Examples

Once configured, you can ask your AI assistant to:

• "Search for the movie Inception in Overseerr"
• "Check if The Matrix has already been requested"
• "Has anyone requested Breaking Bad yet?"
• "Request the TV show Breaking Bad, all seasons"
• "List all pending media requests"
• "Show me all available media in the library"
• "Get details for request ID 123"
• "Approve request ID 45"
• "Show me information about the movie with TMDB ID 550"
• "What's the status of my request for Dune?"

API Reference

The server uses the Overseerr API v1. For more details, see:

• Overseerr API Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Troubleshooting

Connection Issues

1. Verify your Overseerr URL is accessible from where the server runs
2. Ensure your API key is valid (Overseerr Settings → General)
3. Check firewall rules if running remotely

Docker Issues

1. Verify environment variables are set correctly
2. Check container logs: docker logs overseerr-mcp
3. Ensure port 8085 is not already in use

Build Issues

1. Ensure Node.js version is 18.0 or higher
2. Clear node_modules and reinstall: rm -rf node_modules && npm install
3. Rebuild TypeScript: npm run build

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Overseerr - Media request and discovery tool
• Model Context Protocol - Open protocol for AI integrations
• Anthropic - Creators of the MCP standard