Flightradar24 MCP Server

Instructions

Implementation Reference

• src/fr24-client.ts:98-100 (handler)

  Core handler function in FR24Client class that performs the HTTP request to the FR24 API endpoint '/flight-summary/light' using the shared makeRequest method, returning FlightSummaryLight[].

  async getFlightSummaryLight(params: Record<string, any>): Promise<FlightSummaryLight[]> {
    return this.makeRequest<FlightSummaryLight[]>('/flight-summary/light', params);
  }

• src/server.ts:61-74 (schema)

  Zod schema defining the input parameters for the get_flight_summary_light tool (shared with full version), including required date range and optional filters.

  const flightSummaryToolParamsSchema = z.object({
    flight_datetime_from: z.string().min(1).describe('Start datetime (YYYY-MM-DDTHH:MM:SSZ). Requires flight_datetime_to. Cannot be used with flight_ids.'),
    flight_datetime_to: z.string().min(1).describe('End datetime (YYYY-MM-DDTHH:MM:SSZ). Requires flight_datetime_from. Cannot be used with flight_ids.'),
    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>.'),
    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).'),
    sort: z.enum(['asc', 'desc']).optional().describe('Sorting order by first_seen (default: asc).'),
    limit: z.number().optional().describe('Limit of results. Recommended, unless needed. Max 20000.')
  });

• src/server.ts:309-334 (registration)

  MCP tool registration using server.tool(), specifying name, description, input schema, and handler wrapper that validates inputs, cleans parameters, delegates to FR24Client handler, and formats the response as text content.

  server.tool(
    'get_flight_summary_light',
    'Returns key timings and locations of aircraft takeoffs and landings alongside all primary flight, aircraft, and operator information. Both real-time and historical data are available. Data is available starting from 2024-04-07 and will be extended further in the near future. IMPORTANT: flight_datetime_from and flight_datetime_to are required, and at least one additional search parameter (other than sort and limit) should be provided.',
    flightSummaryToolParamsSchema.shape,
    async (params: z.infer<typeof flightSummaryToolParamsSchema>) => {
       try {
        validateHasRequiredParams(params, ['flight_datetime_from', 'flight_datetime_to', 'sort', 'limit']);
        const cleaned = cleanParams(params);
        const result = await fr24Client.getFlightSummaryLight(cleaned);
        return {
          content: [{
            type: 'text' as const,
            text: `Found ${result.length} flight summaries (light details):\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/fr24-client.ts:32-61 (helper)

  Shared helper method in FR24Client for making authenticated HTTP requests to FR24 API endpoints, handling various response structures and errors. Used by getFlightSummaryLight.

  private async makeRequest<T>(endpoint: string, params?: Record<string, any>): Promise<T> {
    try {
      console.log(`Making request to ${endpoint} with params: ${JSON.stringify(params)}`);
      const response = await axios.get(`${this.baseUrl}${endpoint}`, {
        params: params,
        headers: {
          'Accept': 'application/json',
          'Accept-Version': 'v1',
          'Authorization': `Bearer ${this.apiKey}`
        }
      });
      // Handle responses nested under 'data' key, except for count endpoints and single objects
      if (response.data && response.data.data && Array.isArray(response.data.data)) {
        return response.data.data as T;
      }
      // Handle count responses
      if (response.data && typeof response.data.record_count === 'number') {
        return response.data as T;
      }
      // Handle single object responses (like flight tracks, airport info, airline info)
      if (response.data && typeof response.data === 'object' && !Array.isArray(response.data)) {
          return response.data as T;
      }
      // Fallback for unexpected structure
      return response.data as T;
    } catch (error) {
      const message = error instanceof AxiosError ? error.message : 'Unknown error';
      console.error(`API Request Failed: ${endpoint}`, error);
      throw new Error(`Failed request to ${endpoint}: ${message}`);
    }