Overseerr MCP Server

Instructions

Implementation Reference

• src/index.ts:525-572 (registration)

  Registration of the 'manage_media_requests' tool in the ListTools response, including name, description, and detailed inputSchema matching ManageRequestsArgs

  {
    name: 'manage_media_requests',
    description:
      'Manage requests: get/list/approve/decline/delete. Supports filters and batching.\n' +
      'Filters: all|pending|approved|available|processing|unavailable|failed',
    inputSchema: {
      type: 'object',
      properties: {
        action: {
          type: 'string',
          enum: ['get', 'list', 'approve', 'decline', 'delete'],
          description: 'Action',
        },
        requestId: {
          type: 'number',
          description: 'Request ID (single)',
        },
        requestIds: {
          type: 'array',
          items: { type: 'number' },
          description: 'Request IDs (batch)',
        },
        format: {
          type: 'string',
          enum: ['compact', 'standard', 'full'],
          default: 'compact',
        },
        summary: {
          type: 'boolean',
          description: 'Stats instead of list',
          default: false,
        },
        filter: {
          type: 'string',
          enum: ['all', 'pending', 'approved', 'available', 'processing', 'unavailable', 'failed'],
          default: 'all',
        },
        take: { type: 'number', default: 20 },
        skip: { type: 'number', default: 0 },
        sort: {
          type: 'string',
          enum: ['added', 'modified'],
          default: 'added',
        },
      },
      required: ['action'],
    },
  },

• src/types.ts:131-141 (schema)

  TypeScript interface defining the input parameters for manage_media_requests tool (ManageRequestsArgs)

  export interface ManageRequestsArgs {
    action: 'get' | 'list' | 'approve' | 'decline' | 'delete';
    requestId?: number;
    requestIds?: number[];
    format?: 'compact' | 'standard' | 'full';
    summary?: boolean;
    filter?: 'all' | 'pending' | 'approved' | 'available' | 'processing' | 'unavailable' | 'failed';
    take?: number;
    skip?: number;
    sort?: 'added' | 'modified';
  }

• src/index.ts:1732-1752 (handler)

  Primary handler dispatcher for manage_media_requests tool, routes to action-specific sub-handlers

  private async handleManageRequests(args: any) {
    const manageArgs = args as ManageRequestsArgs;
  
    switch (manageArgs.action) {
      case 'get':
        return this.handleGetRequest(manageArgs);
      case 'list':
        return this.handleListRequests(manageArgs);
      case 'approve':
        return this.handleApproveRequests(manageArgs);
      case 'decline':
        return this.handleDeclineRequests(manageArgs);
      case 'delete':
        return this.handleDeleteRequests(manageArgs);
      default:
        throw new McpError(
          ErrorCode.InvalidParams,
          `Unknown action: ${manageArgs.action}`
        );
    }
  }

• src/index.ts:1754-1782 (handler)

  Handler for 'get' action: fetches single request details with caching

  private async handleGetRequest(args: ManageRequestsArgs) {
    if (!args.requestId) {
      throw new McpError(ErrorCode.InvalidParams, 'requestId is required for get action');
    }
  
    const cacheKey = { requestId: args.requestId };
    let request = this.cache.get<MediaRequest>('requests', cacheKey);
  
    if (!request) {
      const response = await this.axiosInstance.get<MediaRequest>(
        `/request/${args.requestId}`
      );
      request = response.data;
      this.cache.set('requests', cacheKey, request);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            args.format === 'full' ? request : this.formatCompactRequest(request),
            null,
            2
          ),
        },
      ],
    };
  }

• src/index.ts:1784-1858 (handler)

  Handler for 'list' action: lists requests with pagination, filtering, sorting, summary stats, and caching

  private async handleListRequests(args: ManageRequestsArgs) {
    const { filter, take, skip, sort, summary } = args;
  
    // If summary mode, fetch all results (don't use pagination)
    if (summary) {
      const params: any = {
        take: 1000, // Fetch large batch to get all/most results
        skip: 0,
        sort: sort || 'added',
      };
  
      if (filter && filter !== 'all') {
        params.filter = filter;
      }
  
      // Don't cache summary queries as they need fresh data
      const response = await this.axiosInstance.get('/requests', { params });
      const requests = response.data;
  
      const statusCounts: Record<string, number> = {};
      requests.results.forEach((r: MediaRequest) => {
        const status = this.getStatusString(r.status);
        statusCounts[status] = (statusCounts[status] || 0) + 1;
      });
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              total: requests.results.length,
              statusBreakdown: statusCounts,
              filter: filter || 'all',
            }, null, 2),
          },
        ],
      };
    }
  
    // Regular list mode - use pagination
    const cacheKey = { filter, take, skip, sort };
    let requests = this.cache.get<{ results: MediaRequest[]; PageInfo: any }>('requests', cacheKey);
  
    if (!requests) {
      const params: any = {
        take: take || 20,
        skip: skip || 0,
        sort: sort || 'added',
      };
  
      if (filter && filter !== 'all') {
        params.filter = filter;
      }
  
      const response = await this.axiosInstance.get('/requests', { params });
      requests = response.data;
      this.cache.set('requests', cacheKey, requests);
    }
  
    const formatted = requests ? requests.results.map(r =>
      args.format === 'full' ? r : this.formatCompactRequest(r)
    ) : [];
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            results: formatted,
            pageInfo: requests?.PageInfo,
          }, null, 2),
        },
      ],
    };
  }