overseerr mcp server

A Model Context Protocol (MCP) integration for Overseerr that enables natural language interaction with your media request system through Claude AI. This server allows you to search for movies and TV shows, make media requests, and manage your Overseerr instance using conversational language.

Example Conversations

Here are some example conversations you can have with Claude using this server:

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]

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]

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]

Features

Media Search

• Search across movies, TV shows, and people
• Get detailed information about media including:
• Title and release date
• Plot overview
• Availability status
• Request status
• Filter by media type (movie/TV/person)
• Natural language queries (e.g., "find recent sci-fi movies" or "search for shows like Breaking Bad")

Media Requests

• Request movies and TV shows
• Specify individual seasons for TV shows
• Track request status
• Get notifications about request updates
• Natural language requests (e.g., "request the latest Batman movie" or "add Succession to my watchlist")

Integration

• Seamless Claude AI integration through stdio transport
• Real-time interaction with your Overseerr instance
• Secure API key handling
• Rate limiting and error handling
• Easy configuration through environment variables

Setup

Prerequisites

• Node.js
• pnpm
• Claude Desktop
• Overseerr instance

Quick Start

1. Install dependencies:

   pnpm install

2. Build the project:

   pnpm build

3. Configure environment:

   # Copy template
   cp .env.template .env
   
   # Edit .env with your values
   OVERSEERR_URL=your_overseerr_url
   OVERSEERR_API_KEY=your_api_key

4. Configure Claude Desktop:

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"
    }
  }
}

Windows (note the double backslashes):

{
  "overseerr": {
    "command": "node",
    "args": ["C:pathtooverseerrpackagesserverdistindex.js"],
    "cwd": "C:pathtooverseerr",
    "transport": {
      "type": "stdio"
    },
    "env": {
      "OVERSEERR_URL": "your_overseerr_url",
      "OVERSEERR_API_KEY": "your_api_key"
    }
  }
}

1. Start the server:

   pnpm start

Technical Details

Project Structure

packages/
├── config/      # Configuration management
├── overseerr/   # Overseerr API client
├── server/      # MCP server implementation
└── shared/      # Shared types and utilities

Available Tools

Search Media (overseerr:search)

Search for movies, TV shows, and people in the 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'
}

Example queries: - "Search for Inception" - "Find TV shows from 2023" - "Look for movies with Tom Hanks"

Request Media (overseerr:request)

Request movies or TV shows to be added to your media 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 requests: - Request a movie: "Request The Matrix" - Request specific seasons: "Add seasons 1-3 of The Office" - Request all seasons: "Request the complete series of Breaking Bad"

Configuration

Environment Variables

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

Error Handling

The server implements robust error handling: - API errors with meaningful messages - Rate limiting protection - Request validation - Connection error recovery

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT