FlightRadar MCP Server

0.1.2 · active · verified Tue Apr 21

The `flightradar-mcp-server` is a Model Context Protocol (MCP) server designed to provide real-time flight tracking and status information. It integrates with the AviationStack API to offer three core functionalities: retrieving detailed flight data by IATA/ICAO code, searching for flights based on various criteria (airline, airports, status), and summarizing flight statuses in a human-readable format. Currently at version 0.1.2, this package appears to be in an early development stage, focusing on extending AI agents like Claude with external flight information capabilities rather than being a standalone, general-purpose API. Its release cadence is ad-hoc given its early version, implying potential for rapid evolution. Key differentiators include its specific integration with the MCP protocol for AI agents, facilitating direct interaction with LLMs, and its direct use of AviationStack for flight data, providing a robust, specialized tool for conversational AI applications requiring flight information.

Common errors

```
Error: API key is missing. Please set AVIATIONSTACK_API_KEY environment variable.
```
cause The `AVIATIONSTACK_API_KEY` environment variable was not set or was provided with an empty value when the server was started.

fix Ensure `AVIATIONSTACK_API_KEY` is correctly configured with a valid API key from aviationstack.com in the environment where the server process runs. For MCP clients, this is typically done in the client's MCP server configuration JSON.
```
node: command not found
```
cause Node.js is not installed on the system or its executable path is not included in the system's PATH environment variable.

fix Download and install the latest LTS version of Node.js (which includes npm) from nodejs.org, and verify its installation by running `node -v` and `npm -v` in your terminal.

Warnings

gotcha This package is explicitly designed as a standalone Model Context Protocol (MCP) server, not a traditional JavaScript library for direct programmatic import. Attempting to `import` or `require` symbols from it will not work as its primary interaction model is via process execution and IPC with AI agents.
Fix: Refer to the package's documentation for running the server as a separate process and configuring your MCP-compatible AI client to interact with it.
gotcha An active API key from AviationStack (obtained at aviationstack.com) is absolutely mandatory for this server to retrieve any flight data. Without it, all flight-related requests will fail. The key must be provided as the `AVIATIONSTACK_API_KEY` environment variable.
Fix: Obtain a valid API key from aviationstack.com and ensure it is correctly set as the `AVIATIONSTACK_API_KEY` environment variable in the execution context of the server, typically within your MCP client's configuration.
gotcha As of version 0.1.2, this package is in an early development stage. This implies that the API, internal structure, and overall functionality may undergo significant, potentially breaking, changes in future minor or even patch releases without strict adherence to semantic versioning until a stable major release.
Fix: Users should monitor the project's repository for updates, carefully review changelogs when upgrading, and be prepared for potential adjustments in their integration or configuration.

Install

npm install flightradar-mcp-server npm
yarn add flightradar-mcp-server yarn
pnpm add flightradar-mcp-server pnpm

Imports

Server Process
wrong:
```
import { startServer } from 'flightradar-mcp-server'
```
correct:
```
This package is run as a Node.js process.
```
The server is started via `node build/index.js` after cloning and building the repository, not imported as a library into other JavaScript code.
AviationStack API Key
wrong:
```
import { setApiKey } from 'flightradar-mcp-server'
```
correct:
```
The API key is passed via the AVIATIONSTACK_API_KEY environment variable.
```
Configuration, including the API key, is external to the server's code; direct programmatic API key setting is not exposed for consumers.
Model Context Protocol (MCP)
wrong:
```
import { getFlightData } from 'flightradar-mcp-server'
```
correct:
```
Interaction occurs over MCP, typically initiated by an AI client like Claude.
```
Functions like `get_flight_data`, `search_flights`, and `get_flight_status` are protocol commands processed by the running server, not exportable JavaScript functions for direct programmatic calls.

Quickstart

Demonstrates the setup, build, and execution of the `flightradar-mcp-server` as a standalone Node.js process, including environment variable configuration for the AviationStack API key.

# Quickstart to set up and run the FlightRadar MCP Server
# This assumes Node.js (v14+) and npm (v6+) are already installed.

# 1. Clone the repository
git clone https://github.com/Cyreslab-AI/flightradar-mcp-server.git
cd flightradar-mcp-server

# 2. Install project dependencies
npm install

# 3. Build the server (compiles TypeScript/JavaScript)
npm run build

# 4. Set your AviationStack API key and run the server
# Replace 'YOUR_AVIATIONSTACK_API_KEY' with your actual key from aviationstack.com
# The server will start and listen for MCP requests.
AVIATIONSTACK_API_KEY="YOUR_AVIATIONSTACK_API_KEY" node build/index.js

# To integrate with an MCP client (e.g., Claude Desktop), refer to the
# 'Configure the server in your MCP settings file' section of the README.

view raw JSON →