Flightradar24 MCP Server

Instructions

Implementation Reference

• src/server.ts:230-251 (handler)

  The MCP tool handler function for 'get_historic_flights_positions_light'. It validates parameters (requiring timestamp and at least one other), cleans optional params, calls FR24Client.getHistoricPositionsLight, formats the response as text with JSON, or returns error.

  async (params: z.infer<typeof historicFlightPositionsSchema>) => {
     try {
      validateHasRequiredParams(params, ['timestamp', 'limit']);
      const { timestamp, ...restParams } = params;
      const cleanedOptionalParams = cleanParams(restParams);
      const result = await fr24Client.getHistoricPositionsLight({ timestamp, ...cleanedOptionalParams });
      return {
        content: [{
          type: 'text' as const,
          text: `Found ${result.length} historic flights (light details) at timestamp ${timestamp}:\n${JSON.stringify(result, null, 2)}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: 'text' as const,
          text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
        }],
        isError: true
      };
    }
  }

• src/server.ts:226-252 (registration)

  Registration of the 'get_historic_flights_positions_light' tool on the MCP server, specifying name, description, input schema, and inline handler function.

  server.tool(
    'get_historic_flights_positions_light',
    'Returns historical aircraft flight movement information including latitude, longitude, speed and altitude. FR24 API provides access to historical flight data, dating back to May 11, 2016, depending on the user\'s subscription plan. IMPORTANT: Timestamp is required, and at least one additional search parameter (other than limit) must be provided and non-empty.',
    historicFlightPositionsSchema.shape,
    async (params: z.infer<typeof historicFlightPositionsSchema>) => {
       try {
        validateHasRequiredParams(params, ['timestamp', 'limit']);
        const { timestamp, ...restParams } = params;
        const cleanedOptionalParams = cleanParams(restParams);
        const result = await fr24Client.getHistoricPositionsLight({ timestamp, ...cleanedOptionalParams });
        return {
          content: [{
            type: 'text' as const,
            text: `Found ${result.length} historic flights (light details) at timestamp ${timestamp}:\n${JSON.stringify(result, null, 2)}`
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: 'text' as const,
            text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
          }],
          isError: true
        };
      }
    }
  );

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

  Zod input schemas: baseFlightPositionsSchema (shared parameters like bounds, flights, etc.) extended by historicFlightPositionsSchema to include required timestamp for the tool.

  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.')
  });
  
  const liveFlightPositionsSchema = baseFlightPositionsSchema;
  const liveFlightPositionsCountSchema = baseFlightPositionsSchema;
  
  const historicFlightPositionsSchema = baseFlightPositionsSchema.extend({
    timestamp: z.number().describe('Unix timestamp for the historical snapshot.'),
  });
  
  const historicFlightPositionsCountSchema = baseFlightPositionsSchema.extend({
    timestamp: z.number().describe('Unix timestamp for the historical snapshot.')
  });

• src/fr24-client.ts:84-86 (helper)

  FR24Client method invoked by the handler to query the FR24 API's historic light flight positions endpoint.

  async getHistoricPositionsLight(params: HistoricFlightPositionsQueryParams): Promise<HistoricFlightPositionLight[]> {
    return this.makeRequest<HistoricFlightPositionLight[]>('/historic/flight-positions/light', params);
  }

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

  Utility functions cleanParams (removes empty/null params) and validateHasRequiredParams (ensures at least one non-excluded param is provided), used in the handler.

  function cleanParams<T extends Record<string, any>>(params: T): Partial<T> {
    const cleaned: Partial<T> = {};
    for (const key in params) {
      if (params[key] !== null && params[key] !== undefined && params[key] !== '') {
        cleaned[key] = params[key];
      }
    }
    return cleaned;
  }
  
  // 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(', ')}`);
    }
  }