Flightradar24 MCP Server

Instructions

Implementation Reference

• src/server.ts:121-141 (handler)

  MCP tool handler function that validates input parameters, cleans them, calls FR24Client.getLivePositionsLight(), and returns the result as formatted text or error response.
  async (params: z.infer<typeof liveFlightPositionsSchema>) => { try { validateHasRequiredParams(params, ['limit']); const cleaned = cleanParams(params); const result = await fr24Client.getLivePositionsLight(cleaned); return { content: [{ type: 'text' as const, text: `Found ${result.length} flights (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/server.ts:31-48 (schema)

  Zod schema defining the input parameters for the live flight positions 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:118-142 (registration)

  Registration of the MCP tool with name, description, input schema, and handler function.
  'get_live_flights_positions_light', 'Returns real-time aircraft flight movement information including latitude, longitude, speed, and altitude. 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.getLivePositionsLight(cleaned); return { content: [{ type: 'text' as const, text: `Found ${result.length} flights (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:66-68 (helper)

  FR24Client method that performs the actual API request for light live flight positions data.
  async getLivePositionsLight(params: LiveFlightPositionsQueryParams): Promise<FlightPositionLight[]> { return this.makeRequest<FlightPositionLight[]>('/live/flight-positions/light', params); }
• src/server.ts:7-14 (helper)

  Helper function to remove null, undefined, and empty string properties from parameters.
  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;