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