Jmagar Overseerr MCP Server

🚀 Overseerr MCP English Documentation

Overseerr MCP is a Model Context Protocol (MCP) integrated into Overseerr, enabling you to achieve natural language interaction with the media request system through Claude AI. This server allows you to use conversational language to search for movies and TV shows, submit media requests, and manage your Overseerr instance.

🚀 Quick Start

Prerequisites

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

Quick Start Steps

1. Install dependencies:

pnpm install

2. Build the project:

pnpm build

3. Configure environment variables:

export OVERSEERR_URL=your-overseerr-instance-url
export OVERSEERR_API_KEY=your-overseerr-api-key

4. Run the server:

pnpm start

💻 Usage Examples

Basic Usage

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

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

You: What available TV shows are there about cooking?
Claude: Let me search for cooking - related TV shows...
[Use overseerr:search and set type='tv' to find cooking shows]

✨ Features

Media Search

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

Media Request

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

Integration

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

🔧 Technical Details

Project Structure

• src/: Contains all source code files, including routes, services, and middleware.
• public/: Stores static resources, such as CSS and JavaScript files.
• package.json: Defines the project's dependencies and scripts.

Technical Tools

Media Search

Interface definition:

interface SearchQuery {
  term: string;
  type?: 'movie' | 'tv' | 'person';
}

Example queries:

• Search for a movie: "Search for Titanic"
• Search for a TV show: "Find Game of Thrones"

Media Request

Interface definition:

interface RequestPayload {
  title: string;
  year: number;
  imdbId?: string;
  seasons?: number[];
}

Example requests:

• Request a movie: "Request the latest Avatar"
• Request specific seasons: "Add seasons 1 to 5 of Friends"
• Request all seasons: "Request the entire Prison Break series"

Error Handling

The server implements powerful error - handling features:

• API errors with meaningful error messages.
• Rate - limiting protection.
• Request validation.
• Connection error recovery.

Configuration Information

Environment Variables

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

Contribution Guide

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