Flightradar24 MCP Server

Instructions

Implementation Reference

• src/server.ts:254-280 (handler)

  Handler function registered for the 'get_historic_flights_count' MCP tool. Validates parameters, extracts timestamp, cleans optional params, fetches count from FR24Client, and returns formatted text response.

  server.tool(
    'get_historic_flights_count',
    'Returns number of historical aircraft flight positions. IMPORTANT: Timestamp is required, and at least one additional search parameter (other than limit) must be provided and non-empty.',
    historicFlightPositionsCountSchema.shape,
    async (params: z.infer<typeof historicFlightPositionsCountSchema>) => {
      try {
        validateHasRequiredParams(params, ['timestamp', 'limit']);
        const { timestamp, ...restParams } = params;
        const cleanedOptionalParams = cleanParams(restParams);
        const result = await fr24Client.getHistoricPositionsCount({ timestamp, ...cleanedOptionalParams });
        return {
          content: [{
            type: 'text' as const,
            text: `Historic flight count at timestamp ${timestamp}: ${result.record_count}`
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: 'text' as const,
            text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
          }],
          isError: true
        };
      }
    }
  );

• src/server.ts:57-59 (schema)

  Zod input schema for the get_historic_flights_count tool, extending baseFlightPositionsSchema with required timestamp.

  const historicFlightPositionsCountSchema = baseFlightPositionsSchema.extend({
    timestamp: z.number().describe('Unix timestamp for the historical snapshot.')
  });

• src/server.ts:31-47 (schema)

  Base Zod schema for flight positions queries used by multiple tools, including get_historic_flights_count via extension.

  const baseFlightPositionsSchema = z.object({
    bounds: z.string().min(1).optional().describe('Coordinates defining an area. Order: north, south, west, east (comma-separated float values).'),
    flights: z.string().min(1).optional().describe('Flight numbers (comma-separated values, max 15).'),
    callsigns: z.string().min(1).optional().describe('Flight callsigns (comma-separated values, max 15).'),
    registrations: z.string().min(1).optional().describe('Aircraft registration numbers (comma-separated values, max 15).'),
    painted_as: z.string().min(1).optional().describe("Aircraft painted in an airline's livery (ICAO code, comma-separated, max 15)."),
    operating_as: z.string().min(1).optional().describe("Aircraft operating under an airline's call sign (ICAO code, comma-separated, max 15)."),
    airports: z.string().min(1).optional().describe('Airports (IATA/ICAO/ISO 3166-1 alpha-2) or countries. Use format: [direction:]<code>. Directions: inbound, outbound, both.'),
    routes: z.string().min(1).optional().describe('Flights between airports/countries (e.g., SE-US, ESSA-JFK). Max 15.'),
    aircraft: z.string().min(1).optional().describe('Aircraft ICAO type codes (comma-separated, max 15).'),
    altitude_ranges: z.string().min(1).optional().describe('Flight altitude ranges in feet (e.g., 0-3000, 5000-7000).'),
    squawks: z.string().min(1).optional().describe('Squawk codes in hex format (comma-separated).'),
    categories: z.string().min(1).optional().describe('Categories of Flights (comma-separated: P, C, M, J, T, H, B, G, D, V, O, N).'),
    data_sources: z.string().min(1).optional().describe('Source of information (comma-separated: ADSB, MLAT, ESTIMATED).'),
    airspaces: z.string().min(1).optional().describe('Flight information region in lower or upper airspace.'),
    gspeed: z.string().min(1).optional().describe('Flight ground speed in knots (single value or range, e.g., 120-140, 80).'),
    limit: z.number().optional().describe('Limit of results. Recommended, unless needed. Max 30000.')

• src/fr24-client.ts:88-90 (helper)

  FR24Client helper method that performs the HTTP request to the FR24 API endpoint for historic flight positions count.

  async getHistoricPositionsCount(params: HistoricFlightPositionsCountQueryParams): Promise<RecordCountResponse> {
    return this.makeRequest<RecordCountResponse>('/historic/flight-positions/count', params);
  }

• src/server.ts:17-29 (helper)

  Helper function used in the handler to validate that required parameters are provided.

  // Helper function to validate that at least one meaningful parameter is provided
  function validateHasRequiredParams(params: Record<string, any>, excludeKeys: string[] = ['limit']): void {
    const meaningfulParams = Object.entries(params).filter(([key, value]) => 
      !excludeKeys.includes(key) && 
      value !== null && 
      value !== undefined && 
      value !== ''
    );
    
    if (meaningfulParams.length === 0) {
      throw new Error(`At least one parameter other than ${excludeKeys.join(', ')} must be provided and non-empty. Available parameters: ${Object.keys(params).filter(k => !excludeKeys.includes(k)).join(', ')}`);
    }
  }