Overseerr MCP Server

Instructions

Implementation Reference

• src/index.ts:574-624 (registration)

  Registration of the get_media_details tool, including name, description, and detailed inputSchema for single/batch requests with level/field control.
  name: 'get_media_details', description: 'Get media details. Single/batch with level control (basic/standard/full).', inputSchema: { type: 'object', properties: { mediaType: { type: 'string', enum: ['movie', 'tv'], description: 'Media type (single)', }, mediaId: { type: 'number', description: 'TMDB ID (single)', }, items: { type: 'array', items: { type: 'object', properties: { mediaType: { type: 'string', enum: ['movie', 'tv'] }, mediaId: { type: 'number' }, }, required: ['mediaType', 'mediaId'], }, description: 'Batch items', }, level: { type: 'string', enum: ['basic', 'standard', 'full'], description: 'Detail level', default: 'standard', }, fields: { type: 'array', items: { type: 'string' }, description: 'Specific fields', }, format: { type: 'string', enum: ['compact', 'standard', 'full'], default: 'compact', }, language: { type: 'string', description: 'Language code', default: 'en', }, }, }, },
• src/index.ts:1990-2017 (handler)

  Core single-item handler: fetches TMDB details via Overseerr API, caches result, applies filtering by level or fields, returns JSON.
  private async handleSingleDetails(args: GetDetailsArgs) { const { mediaType, mediaId, level, fields, language } = args; const cacheKey = { mediaType, mediaId, language: language || 'en' }; let details = this.cache.get<MediaDetails>('mediaDetails', cacheKey); if (!details) { const params = language ? { language } : {}; const response = await this.axiosInstance.get<MediaDetails>( `/${mediaType}/${mediaId}`, { params } ); details = response.data; this.cache.set('mediaDetails', cacheKey, details); } // Apply level filtering const filtered = this.filterDetailsByLevel(details, level || 'standard', fields); return { content: [ { type: 'text', text: JSON.stringify(filtered, null, 2), }, ], }; }
• src/index.ts:2019-2066 (handler)

  Batch handler: parallel fetches details for multiple items using retry, caching, filtering; summarizes success/errors.
  private async handleBatchDetails(args: GetDetailsArgs) { const items = args.items!; const results = await batchWithRetry( items, async (item) => { const cacheKey = { mediaType: item.mediaType, mediaId: item.mediaId, language: args.language || 'en' }; let details = this.cache.get<MediaDetails>('mediaDetails', cacheKey); if (!details) { const response = await this.axiosInstance.get<MediaDetails>( `/${item.mediaType}/${item.mediaId}`, { params: args.language ? { language: args.language } : {} } ); details = response.data; this.cache.set('mediaDetails', cacheKey, details); } return this.filterDetailsByLevel(details, args.level || 'standard', args.fields); } ); const successful = results.filter(r => r.success); const failed = results.filter(r => !r.success); return { content: [ { type: 'text', text: JSON.stringify({ summary: { total: items.length, successful: successful.length, failed: failed.length }, results: successful.map(r => r.result), errors: failed.map(r => ({ item: r.item, error: r.error?.message || 'Unknown error' })) }, null, 2), } ] }; }
• src/index.ts:1971-1988 (handler)

  Entry point handler dispatched from tool call: routes to single or batch based on input.
  private async handleGetDetails(args: GetDetailsArgs) { const detailsArgs = args as GetDetailsArgs; // Batch mode if (detailsArgs.items && detailsArgs.items.length > 0) { return this.handleBatchDetails(detailsArgs); } // Single mode if (!detailsArgs.mediaType || !detailsArgs.mediaId) { throw new McpError( ErrorCode.InvalidParams, 'Must provide mediaType and mediaId (or items array for batch)' ); } return this.handleSingleDetails(detailsArgs); }
• src/index.ts:282-339 (helper)

  Filters media details output by level (basic/standard/full) or specific fields using predefined mappers; used by both single/batch handlers.
  private filterDetailsByLevel( details: MediaDetails, level: string, fields?: string[] ): any { // If specific fields requested, return only those if (fields && fields.length > 0) { const filtered: any = {}; const item = { mediaType: details.mediaType || 'movie', id: details.id }; fields.forEach(field => { const mapper = FIELD_MAP[field]; if (mapper) { const value = mapper(item, details); if (value !== undefined) { filtered[field] = value; } } }); return filtered; } // Level-based filtering switch (level) { case 'basic': return { id: details.id, mediaType: details.mediaType, title: details.title || details.name, overview: details.overview, year: details.releaseDate?.substring(0, 4) || details.firstAirDate?.substring(0, 4), rating: details.voteAverage, mediaInfo: details.mediaInfo ? { status: this.getMediaStatusString(details.mediaInfo.status), hasRequests: (details.mediaInfo.requests?.length || 0) > 0, } : undefined, }; case 'standard': return { mediaType: details.mediaType, id: details.id, title: details.title || details.name, overview: details.overview, releaseDate: details.releaseDate || details.firstAirDate, genres: details.genres, voteAverage: details.voteAverage, runtime: details.runtime, numberOfSeasons: details.numberOfSeasons, numberOfEpisodes: details.numberOfEpisodes, seasons: details.seasons, mediaInfo: details.mediaInfo, }; case 'full': default: return details; } }
• src/types.ts:143-154 (schema)

  TypeScript interface defining input parameters for get_media_details tool, matching the JSON schema.
  export interface GetDetailsArgs { mediaType?: 'movie' | 'tv'; mediaId?: number; items?: Array<{ mediaType: 'movie' | 'tv'; mediaId: number; }>; level?: 'basic' | 'standard' | 'full'; fields?: string[]; format?: 'compact' | 'standard' | 'full'; language?: string; }