Flightradar24 MCP Server

Instructions

Implementation Reference

• src/server.ts:202-223 (handler)

  The MCP tool handler function. Validates input parameters (excluding timestamp and limit), cleans optional params, calls FR24Client.getHistoricPositionsFull, formats the result as JSON text response or error.

  async (params: z.infer<typeof historicFlightPositionsSchema>) => {
    try {
      validateHasRequiredParams(params, ['timestamp', 'limit']);
      const { timestamp, ...restParams } = params;
      const cleanedOptionalParams = cleanParams(restParams);
      const result = await fr24Client.getHistoricPositionsFull({ timestamp, ...cleanedOptionalParams });
      return {
        content: [{
          type: 'text' as const,
          text: `Found ${result.length} historic flights (full 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:53-55 (schema)

  Zod schema for tool inputs, extending base schema with required timestamp.

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

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

  Base Zod schema defining common query parameters for flight positions (live and historic).

  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/server.ts:198-224 (registration)

  Registration of the MCP tool using McpServer.tool(), specifying name, description, input schema, and inline handler function.

  server.tool(
    'get_historic_flights_positions_full',
    'Returns historical aircraft flight movement information including latitude, longitude, speed, and altitude alongside key flight and aircraft information such as origin, destination, callsign, registration and aircraft type. 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.getHistoricPositionsFull({ timestamp, ...cleanedOptionalParams });
        return {
          content: [{
            type: 'text' as const,
            text: `Found ${result.length} historic flights (full 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/fr24-client.ts:80-82 (helper)

  FR24Client helper method called from tool handler to perform the HTTP API request to FR24's historic full positions endpoint.

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