Overseerr MCP server for AI agents

The Overseerr MCP server provides a conversational interface to your Overseerr media request system through Claude AI. This integration allows you to search for movies and TV shows, make requests, and manage your media library using natural language commands.

Installation

Prerequisites

Node.js
pnpm
Claude Desktop
An existing Overseerr instance

Setup Instructions

Install the required dependencies:

pnpm install

Build the project:

pnpm build

Configure your environment:

# Copy the template
cp .env.template .env

# Edit the .env file with your values
OVERSEERR_URL=your_overseerr_url
OVERSEERR_API_KEY=your_api_key

Configure Claude Desktop:

For Linux/Mac:

{
  "overseerr": {
    "command": "node",
    "args": ["/path/to/overseerr/packages/server/dist/index.js"],
    "cwd": "/path/to/overseerr",
    "transport": {
      "type": "stdio"
    },
    "env": {
      "OVERSEERR_URL": "your_overseerr_url",
      "OVERSEERR_API_KEY": "your_api_key"
    }
  }
}

For Windows:

{
  "overseerr": {
    "command": "node",
    "args": ["C:\\path\\to\\overseerr\\packages\\server\\dist\\index.js"],
    "cwd": "C:\\path\\to\\overseerr",
    "transport": {
      "type": "stdio"
    },
    "env": {
      "OVERSEERR_URL": "your_overseerr_url",
      "OVERSEERR_API_KEY": "your_api_key"
    }
  }
}

Start the server:

pnpm start

Usage Guide

Using the Search Feature

The overseerr:search tool allows you to search for media in your Overseerr database:

{
  // The search query - can be a title, person, or general description
  query: string,
  
  // Optional: Filter by type
  // - 'movie': Only search movies
  // - 'tv': Only search TV shows
  // - 'person': Only search people
  type?: 'movie' | 'tv' | 'person'
}

Making Media Requests

The overseerr:request tool lets you request media to be added to your library:

{
  // The TMDB ID of the media to request
  mediaId: number,
  
  // Type of media being requested
  // - 'movie': Request a movie
  // - 'tv': Request a TV show
  mediaType: 'movie' | 'tv',
  
  // Optional: For TV shows, specify which seasons to request
  // If not provided, requests all available seasons
  seasons?: number[]
}

Example Conversations

Here are some examples of how to interact with the Overseerr MCP through Claude:

Searching for Media

You: Can you find any recent sci-fi movies?
Claude: Let me search for recent science fiction films...
[Uses overseerr:search to find recent sci-fi movies]

Requesting Media

You: That looks good! Can you request the second one?
Claude: I'll request that movie for you...
[Uses overseerr:request to submit the media request]

Searching for TV Shows

You: What TV shows are available about cooking?
Claude: I'll search for cooking-related TV shows...
[Uses overseerr:search with type='tv' to find cooking shows]

Configuration Options

Environment Variables

OVERSEERR_URL: The URL of your Overseerr instance
OVERSEERR_API_KEY: Your Overseerr API key for authentication

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "overseerr" '{"command":"node","args":["packages/server/dist/index.js"],"cwd":"","transport":{"type":"stdio"},"env":{"OVERSEERR_URL":"","OVERSEERR_API_KEY":""}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "overseerr": {
            "command": "node",
            "args": [
                "packages/server/dist/index.js"
            ],
            "cwd": "",
            "transport": {
                "type": "stdio"
            },
            "env": {
                "OVERSEERR_URL": "",
                "OVERSEERR_API_KEY": ""
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "overseerr": {
            "command": "node",
            "args": [
                "packages/server/dist/index.js"
            ],
            "cwd": "",
            "transport": {
                "type": "stdio"
            },
            "env": {
                "OVERSEERR_URL": "",
                "OVERSEERR_API_KEY": ""
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect