Overseerr MCP Server

Instructions

Implementation Reference

• src/types.ts:112-129 (schema)

  TypeScript interface defining the input arguments/schema for the 'request_media' tool, used in registration and handler.

  export interface RequestMediaArgs {
    mediaType?: 'movie' | 'tv';
    mediaId?: number;
    items?: Array<{
      mediaType: 'movie' | 'tv';
      mediaId: number;
      seasons?: number[] | 'all';
      is4k?: boolean;
    }>;
    seasons?: number[] | 'all';
    is4k?: boolean;
    serverId?: number;
    profileId?: number;
    rootFolder?: string;
    validateFirst?: boolean;
    dryRun?: boolean;
    confirmed?: boolean;
  }

• src/index.ts:455-523 (registration)

  MCP tool registration in the server's listTools handler, defining the 'request_media' tool name, description, and inputSchema.

  name: 'request_media',
  description:
    'Request media with auto-confirm for TV ≤24 eps. Single/batch with validation.\n' +
    'Confirm: Movies auto | TV ≤24 eps auto | TV >24 eps needs confirmed:true\n' +
    'TV needs seasons (array or "all"). "all"=no specials; [0,1,2]=with specials',
  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' },
            seasons: {
              oneOf: [
                { type: 'array', items: { type: 'number' } },
                { type: 'string', enum: ['all'] },
              ],
              description: 'TV seasons (REQUIRED). "all"=no season 0 (specials); [0,1,2]=with specials',
            },
            is4k: { type: 'boolean' },
          },
          required: ['mediaType', 'mediaId'],
        },
        description: 'Batch items',
      },
      seasons: {
        oneOf: [
          { type: 'array', items: { type: 'number' } },
          { type: 'string', enum: ['all'] },
        ],
        description: 'TV seasons. "all"=no season 0 (specials); [0,1,2]=with specials',
      },
      is4k: {
        type: 'boolean',
        description: 'Request 4K',
        default: false,
      },
      serverId: { type: 'number' },
      profileId: { type: 'number' },
      rootFolder: { type: 'string' },
      validateFirst: {
        type: 'boolean',
        description: 'Check existing',
        default: true,
      },
      dryRun: {
        type: 'boolean',
        description: 'Preview only',
        default: false,
      },
      confirmed: {
        type: 'boolean',
        description: 'Confirm multi-season',
        default: false,
      },
    },
  },

• src/index.ts:1466-1483 (handler)

  Main entry point handler for 'request_media' tool calls, dispatched from the generic CallToolRequestSchema handler. Dispatches to batch or single request logic.

  private async handleRequestMedia(args: any) {
    const requestArgs = args as RequestMediaArgs;
  
    // Batch mode
    if (requestArgs.items && requestArgs.items.length > 0) {
      return this.handleBatchRequest(requestArgs);
    }
  
    // Single mode
    if (!requestArgs.mediaType || !requestArgs.mediaId) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Must provide mediaType and mediaId (or items array for batch)'
      );
    }
  
    return this.handleSingleRequest(requestArgs);
  }

• src/index.ts:1485-1686 (handler)

  Core single-item request handler implementing validation (TV seasons required), season expansion ('all' -> actual seasons excluding specials), pre-request availability check, auto-confirmation for small TV requests, dry-run preview, and API request to Overseerr.

  private async handleSingleRequest(args: RequestMediaArgs) {
    const { mediaType, mediaId, seasons, is4k, validateFirst, dryRun, confirmed } = args;
  
    // Validate TV show requests have seasons specified
    if (mediaType === 'tv' && !seasons) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'seasons parameter is required for TV show requests. Use seasons: [1,2,3] for specific seasons or seasons: "all" for all seasons.'
      );
    }
  
    // Expand "all" to actual season numbers (excluding season 0) early in the function
    let expandedSeasons: number[] | undefined = undefined;
    if (mediaType === 'tv' && seasons) {
      if (seasons === 'all') {
        const response = await this.axiosInstance.get<MediaDetails>(`/tv/${mediaId}`);
        const details = response.data;
        
        // Get all regular seasons (exclude season 0 - specials)
        const regularSeasons = details.seasons?.filter(s => s.seasonNumber > 0) || [];
        expandedSeasons = regularSeasons.map(s => s.seasonNumber);
        
        // If no regular seasons found, fall back to numberOfSeasons
        if (expandedSeasons.length === 0 && details.numberOfSeasons) {
          expandedSeasons = Array.from({ length: details.numberOfSeasons }, (_, i) => i + 1);
        }
      } else {
        // Already an array, use as-is
        expandedSeasons = seasons as number[];
      }
    }
  
    // Validate first if requested
    if (validateFirst) {
      const detailsCacheKey = { mediaType, mediaId };
      let details = this.cache.get<MediaDetails>('mediaDetails', detailsCacheKey);
      
      if (!details) {
        const response = await this.axiosInstance.get<MediaDetails>(
          `/${mediaType}/${mediaId}`
        );
        details = response.data;
        this.cache.set('mediaDetails', detailsCacheKey, details);
      }
  
      const mediaInfo = details.mediaInfo;
      if (mediaInfo?.requests && mediaInfo.requests.length > 0) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: false,
                status: 'ALREADY_REQUESTED',
                message: `${details.title || details.name} is already requested`,
                existingRequests: mediaInfo.requests.map(r => ({
                  id: r.id,
                  status: this.getStatusString(r.status),
                  requestedBy: r.requestedBy.displayName || r.requestedBy.email,
                  createdAt: r.createdAt,
                })),
              }, null, 2),
            },
          ],
        };
      }
  
      if (mediaInfo?.status === 5) { // AVAILABLE
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: false,
                status: 'ALREADY_AVAILABLE',
                message: `${details.title || details.name} is already available`,
              }, null, 2),
            },
          ],
        };
      }
    }
  
    // Multi-season confirmation check
    if (mediaType === 'tv' && !confirmed && expandedSeasons) {
      const requireConfirm = process.env.REQUIRE_MULTI_SEASON_CONFIRM !== 'false';
      
      if (requireConfirm) {
        // Get details to calculate episode count
        const response = await this.axiosInstance.get<MediaDetails>(`/tv/${mediaId}`);
        const details = response.data;
  
        const totalSeasons = details.numberOfSeasons || 0;
        const seasonsToRequest = expandedSeasons;
  
        // Calculate total episode count for requested seasons
        let totalEpisodes = 0;
        if (details.seasons) {
          seasonsToRequest.forEach((seasonNum: number) => {
            const seasonData = details.seasons?.find(s => s.seasonNumber === seasonNum);
            if (seasonData) {
              totalEpisodes += seasonData.episodeCount;
            }
          });
        }
  
        // Only require confirmation if episode count exceeds threshold (24)
        const EPISODE_THRESHOLD = 24;
        if (totalEpisodes > EPISODE_THRESHOLD) {
          // Build message including episode count for context
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  requiresConfirmation: true,
                  media: {
                    totalSeasons,
                    totalEpisodes: details.numberOfEpisodes,
                    requestingSeasons: seasonsToRequest,
                    requestingEpisodes: totalEpisodes,
                    threshold: EPISODE_THRESHOLD,
                  },
                  message: `This will request ${seasonsToRequest.length} season(s) with ${totalEpisodes} episodes of ${details.name}. Add "confirmed: true" to proceed.`,
                  confirmWith: {
                    ...args,
                    confirmed: true,
                  },
                }, null, 2),
              },
            ],
          };
        }
      }
    }
  
    // Dry run - don't actually request
    if (dryRun) {
      const response = await this.axiosInstance.get<MediaDetails>(
        `/${mediaType}/${mediaId}`
      );
      const details = response.data;
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              dryRun: true,
              wouldRequest: {
                title: details.title || details.name,
                mediaType,
                mediaId,
                seasons: mediaType === 'tv' ? expandedSeasons : undefined,
                is4k: is4k || false,
              },
              message: 'Dry run - no request was made. Remove "dryRun: true" to actually request.',
            }, null, 2),
          },
        ],
      };
    }
  
    // Actually make the request
    const requestBody: any = {
      mediaType,
      mediaId,
      is4k: is4k || false,
    };
  
    // Use expandedSeasons (array) to ensure season 0 is not included
    if (mediaType === 'tv' && expandedSeasons) {
      requestBody.seasons = expandedSeasons;
    }
  
    if (args.serverId) requestBody.serverId = args.serverId;
    if (args.profileId) requestBody.profileId = args.profileId;
    if (args.rootFolder) requestBody.rootFolder = args.rootFolder;
  
    const response = await withRetry(async () => {
      return await this.axiosInstance.post('/request', requestBody);
    });
  
    // Invalidate caches
    this.cache.invalidate('requests');
    this.cache.invalidate('mediaDetails');
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            requestId: response.data.id,
            status: this.getStatusString(response.data.status),
            message: `Successfully requested ${response.data.media.title || response.data.media.name}`,
            seasonsRequested: response.data.seasons?.map((s: any) => s.seasonNumber),
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:1688-1730 (handler)

  Batch request handler for multiple items, using batchWithRetry to call handleSingleRequest on each item and aggregate results.

  private async handleBatchRequest(args: RequestMediaArgs) {
    const items = args.items!;
  
    const results = await batchWithRetry(
      items,
      async (item) => {
        const singleArgs = {
          ...args,
          mediaType: item.mediaType,
          mediaId: item.mediaId,
          seasons: item.seasons,
          is4k: item.is4k,
          items: undefined,
        };
        
        const result = await this.handleSingleRequest(singleArgs);
        return JSON.parse(result.content[0].text);
      }
    );
  
    const successful = results.filter(r => r.success && r.result?.success);
    const failed = results.filter(r => !r.success || !r.result?.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 || r.result?.message || 'Unknown error',
            })),
          }, null, 2),
        },
      ],
    };
  }