Flightradar24 MCP Server

Instructions

Implementation Reference

• src/server.ts:148-167 (handler)

  The MCP tool handler function that validates input parameters, cleans them, fetches full live flight positions from FR24Client, and returns a formatted text response with the data or error.

  async (params: z.infer<typeof liveFlightPositionsSchema>) => {
     try {
      validateHasRequiredParams(params, ['limit']);
      const cleaned = cleanParams(params);
      const result = await fr24Client.getLivePositionsFull(cleaned);
      return {
        content: [{
          type: 'text' as const,
          text: `Found ${result.length} flights (full 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/server.ts:31-48 (schema)

  Zod schema for input parameters used by the get_live_flights_positions_full tool (baseFlightPositionsSchema, aliased as liveFlightPositionsSchema).

  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:144-169 (registration)

  MCP server tool registration for 'get_live_flights_positions_full', including name, description, input schema, and handler function.

  server.tool(
    'get_live_flights_positions_full',
    'Returns real-time 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. IMPORTANT: At least one search parameter (other than limit) must be provided and non-empty. Choose from: bounds, flights, callsigns, registrations, painted_as, operating_as, airports, routes, aircraft, altitude_ranges, squawks, categories, data_sources, airspaces, gspeed.',
    liveFlightPositionsSchema.shape,
    async (params: z.infer<typeof liveFlightPositionsSchema>) => {
       try {
        validateHasRequiredParams(params, ['limit']);
        const cleaned = cleanParams(params);
        const result = await fr24Client.getLivePositionsFull(cleaned);
        return {
          content: [{
            type: 'text' as const,
            text: `Found ${result.length} flights (full 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:70-72 (helper)

  FR24Client helper method that makes the HTTP API request to fetch full live flight positions data.

  async getLivePositionsFull(params: LiveFlightPositionsQueryParams): Promise<FlightPositionFull[]> {
    return this.makeRequest<FlightPositionFull[]>('/live/flight-positions/full', params);
  }

• src/types.ts:104-115 (schema)

  TypeScript type definition for the full flight position data returned by the tool.

  export interface FlightPositionFull extends FlightPositionLight {
    flight: string;
    type: string;
    reg: string;
    painted_as: string;
    operating_as: string;
    orig_iata: string;
    orig_icao: string;
    dest_iata: string;
    dest_icao: string;
    eta: string; // ISO 8601 format
  }