🛩️ FlightRadar24-SPAZ MCP Server

⚡ The Ultimate FlightRadar24 MCP Server - Lightning-fast, feature-rich, and incredibly powerful flight tracking at your fingertips

FlightRadar24-SPAZ is the definitive Model Context Protocol (MCP) server for comprehensive flight tracking, emergency detection, and aviation analytics. Built for speed, reliability, and ease of use.

NPM Package: https://www.npmjs.com/package/flightradar24-spaz
GitHub Repository: https://github.com/CG-Labs/FlightRadar24-SPAZ-MCP (Currently Private)

✨ Features

🚀 Core Capabilities

• Real-time Flight Tracking - Track any flight globally with live position updates
• Emergency Detection - Instant alerts for squawk codes (7500, 7600, 7700, 7777)
• Airport Statistics - Comprehensive analytics for any airport worldwide
• Airline Performance - Detailed statistics and on-time performance metrics
• Route Analysis - Deep insights into specific flight routes
• Weather Integration - Real-time METAR/TAF weather data
• Browser Visualization - Interactive real-time flight map with Leaflet.js

🎯 Advanced Features

• Customizable Alert Rules - Create complex alert conditions for airlines, flights, airports, delays
• Multi-format Data Export - Export data as JSON, CSV, or KML
• Smart Caching - LRU cache strategy for optimal performance
• WebSocket Updates - Real-time flight position streaming via Socket.IO
• Comprehensive Statistics - Delay analysis, on-time performance, fleet analytics
• Emergency Announcements - Automatic emergency detection and notification system

⚡ Performance

• Lightning Fast - Optimized caching and parallel processing
• Low Latency - Sub-second response times
• Efficient Memory Usage - Smart LRU cache management
• Scalable Architecture - Handle thousands of concurrent flight tracks

🚀 Quick Start

Installation

Install globally via npm:

npm install -g flightradar24-spaz

Or run directly with npx (no installation required):

npx flightradar24-spaz

Configuration

Create a .env file in your project directory:

# FlightRadar24 API Configuration (optional for enhanced features)
FLIGHTRADAR24_API_KEY=your_api_key_here

# Server Configuration
SERVER_PORT=3456
SERVER_HOST=localhost

# Alert Configuration  
ALERT_WEBHOOK_URL=https://your-webhook-url.com/alerts
ALERT_CHECK_INTERVAL=10

Note: The API key is optional. The server works without it but some features may be limited.

Usage with Claude Desktop or Claude Code

Add to your Claude Desktop configuration (claude_desktop_config.json) or use Claude Code CLI:

{
  "mcpServers": {
    "flightradar24-spaz": {
      "command": "npx",
      "args": ["flightradar24-spaz"],
      "env": {
        "FLIGHTRADAR24_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or for Claude Code CLI:

# Add as MCP server to Claude Code
claude mcp add flightradar24-spaz npx flightradar24-spaz

📡 Available MCP Tools

Flight Operations

get_flights

Get real-time flight positions with advanced filtering.

{
  "bounds": {
    "north": 60, "south": 40,
    "east": 10, "west": -10
  },
  "airline": "BAW",           // Filter by airline
  "emergency_only": true,     // Only emergency flights
  "altitude_min": 30000,      // Minimum altitude (feet)
  "limit": 100                // Max results
}

get_flight_details

Get comprehensive details about a specific flight.

{
  "flight_id": "2c8f3a2d",
  "include_track": true       // Include flight path history
}

track_flight

Start real-time tracking of a specific flight.

{
  "flight_id": "2c8f3a2d",
  "interval_seconds": 10      // Update frequency
}

Emergency Detection

detect_emergencies

Detect and monitor all emergency flights globally.

{
  "auto_alert": true          // Enable automatic alerts
}

Emergency squawk codes detected:

• 7500 - Hijack
• 7600 - Radio Failure
• 7700 - General Emergency
• 7777 - Military Intercept

Airport Analytics

get_airport_statistics

Calculate comprehensive statistics for any airport.

{
  "airport_code": "KLAX",
  "date": "2024-01-15"       // Optional, defaults to today
}

Returns:

• Total flights (departures/arrivals)
• On-time performance percentage
• Average delay minutes
• Top destinations and origins
• Top airlines
• Aircraft type distribution
• Busiest hour analysis

Alert Management

add_alert_rule

Create custom alert rules with complex conditions.

{
  "name": "Heathrow Emergencies",
  "type": "emergency",
  "conditions": {
    "airports": ["EGLL"],
    "emergency_types": ["GENERAL_EMERGENCY", "HIJACK"]
  },
  "actions": [
    {
      "type": "webhook",
      "config": {
        "url": "https://your-webhook.com"
      }
    }
  ]
}

Alert types supported:

• emergency - Squawk code alerts
• delay - Delay threshold alerts
• route - Specific route monitoring
• airline - Airline-specific alerts
• airport - Airport activity alerts
• custom - Complex custom conditions

Map Visualization

open_map

Open the interactive real-time flight map in your browser.

{
  "center": { "lat": 51.5074, "lng": -0.1278 },
  "zoom": 8,
  "auto_refresh": true       // Enable live updates
}

Features:

• Real-time flight positions
• Emergency highlighting
• Flight details on click
• Dark theme optimized
• WebSocket live updates

Data Export

export_data

Export flight data in various formats.

{
  "format": "kml",           // json, csv, or kml
  "data_type": "flights"     // flights, alerts, or statistics
}

🌟 Advanced Usage Examples

Monitor Specific Airline Delays

// Create alert for United Airlines delays > 30 minutes
{
  "tool": "add_alert_rule",
  "arguments": {
    "name": "United Major Delays",
    "type": "delay",
    "conditions": {
      "airlines": ["UAL"],
      "delay_threshold_minutes": 30
    },
    "actions": [
      { "type": "console" },
      { "type": "webhook", "config": { "url": "https://alerts.com" }}
    ]
  }
}

Track Multiple Emergency Flights

// Start monitoring all emergencies with auto-alerts
{
  "tool": "detect_emergencies",
  "arguments": {
    "auto_alert": true
  }
}

// Then open map to visualize
{
  "tool": "open_map",
  "arguments": {
    "auto_refresh": true
  }
}

Generate Airport Performance Report

// Get comprehensive statistics for JFK
{
  "tool": "get_airport_statistics",
  "arguments": {
    "airport_code": "KJFK",
    "date": "2024-01-15"
  }
}

📊 Performance & Caching

The server implements intelligent caching strategies:

• Flight Positions: 10-second cache
• Flight Details: 30-second cache
• Airport Data: 60-second cache
• Weather Data: 5-minute cache
• Statistics: 5-minute cache

Cache statistics available via:

{ "tool": "get_cache_stats" }

🔒 Security & Privacy

• No data persistence - All data is fetched real-time
• Secure API handling - API keys stored in environment variables
• Rate limiting - Automatic request throttling
• Error handling - Comprehensive error management
• .env protection - Sensitive data never committed to repository

Important: The .env file is automatically excluded from npm publishing and git commits.

🛠️ Development

Local Development

# Clone the repository (currently private)
git clone https://github.com/CG-Labs/FlightRadar24-SPAZ-MCP.git
cd FlightRadar24-SPAZ-MCP

# Install dependencies
npm install

# Create .env file
cp .env.example .env
# Edit .env with your configuration

# Build the project
npm run build

# Run in development mode
npm run dev

Building from Source

npm run build          # Compile TypeScript
npm run test          # Run tests
npm run lint          # Type checking

Project Structure

flightradar24-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── config.ts             # Configuration management
│   ├── types.ts              # TypeScript interfaces
│   └── services/
│       ├── flightradar24-client.ts  # API client
│       ├── alert-manager.ts         # Alert system
│       ├── statistics-calculator.ts # Analytics engine
│       ├── map-visualizer.ts        # Web interface
│       ├── cache-manager.ts         # LRU cache
│       └── logger.ts                # Logging utility
├── dist/                     # Compiled JavaScript
├── .env.example             # Environment template
├── package.json             # NPM configuration
├── tsconfig.json           # TypeScript config
└── README.md               # Documentation

🤝 Contributing

While this repository is currently private, we welcome feedback and suggestions. Please open an issue on GitHub for:

• Bug reports
• Feature requests
• Documentation improvements
• Performance optimizations

📜 License

MIT License - see LICENSE file for details.

👨‍💻 Author

Created by DAK - Building the future of flight tracking, one line of code at a time.

🙏 Acknowledgments

• FlightRadar24 for their comprehensive flight data API
• Model Context Protocol team for the MCP SDK
• The aviation community for continuous support

⚠️ Disclaimer

This is an independent project and is not affiliated with, endorsed by, or sponsored by FlightRadar24 AB. FlightRadar24 is a registered trademark of FlightRadar24 AB.

🚨 Emergency Contact

If you detect a real aviation emergency through this system, immediately contact local aviation authorities:

• USA: Contact FAA at 1-866-TELL-FAA
• Europe: Contact local ATC immediately
• Emergency: Always dial local emergency services

FlightRadar24-SPAZ - Where every flight matters ✈️

Powered by passion, built for performance