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
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
- Install dependencies:
pnpm install
- Build the project:
pnpm build
- Configure environment:
# Copy template
cp .env.template .env
# Edit .env with your values
OVERSEERR_URL=your_overseerr_url
OVERSEERR_API_KEY=your_api_key
- 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"
}
}
}
- 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 URLOVERSEERR_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
- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
License
MIT
