Glama
Sign In

Overseerr MCP Server

by jmagar
Verified
GitHub
TypeScript
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

  • Provides tools for interacting with Overseerr, a request management and media discovery tool for Plex, allowing users to search for movies and TV shows, get detailed information about media, request media to be added to their library, and view and manage existing requests.

Overseerr MCP

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

  • 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
  1. Build the project:
pnpm build
  1. Configure environment:
# Copy template cp .env.template .env # Edit .env with your values OVERSEERR_URL=your_overseerr_url OVERSEERR_API_KEY=your_api_key
  1. 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:\\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" } } }
  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

You must be authenticated.

A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

Allows Claude to interact with Overseerr, enabling users to search, request, and manage media for their Plex library through natural language.

  1. Example Conversations
    1. Features
      1. Media Search
      2. Media Requests
      3. Integration
    2. Setup
      1. Prerequisites
      2. Quick Start
    3. Technical Details
      1. Project Structure
      2. Available Tools
      3. Configuration
      4. Error Handling
    4. Contributing
      1. License

        Related Resources