Aerospace MCP - Flight Planning API & MCP Server

A comprehensive aerospace research and flight planning service providing both HTTP API and Model Context Protocol (MCP) integration. Built with FastMCP for streamlined MCP server development. Features intelligent airport resolution, great-circle route calculation, aircraft performance estimation, atmospheric modeling, coordinate frame transformations, aerodynamic analysis, propeller performance modeling, rocket trajectory optimization, orbital mechanics calculations, and spacecraft trajectory planning for aerospace operations.

⚠️ SAFETY DISCLAIMER

THIS SOFTWARE IS FOR EDUCATIONAL, RESEARCH, AND DEVELOPMENT PURPOSES ONLY

• NOT FOR REAL NAVIGATION: Do not use for actual flight planning or navigation
• NOT CERTIFIED: This system is not certified by any aviation authority
• ESTIMATES ONLY: Performance calculations are theoretical estimates
• NO WEATHER DATA: Does not account for weather, NOTAMs, or airspace restrictions
• NO LIABILITY: Authors assume no responsibility for any consequences of use

For real flight planning, always use certified aviation software and consult official sources including NOTAMs, weather reports, and air traffic control.

🚀 Quick Start

The only prerequisite is uv, which also fetches Python 3.11+ if your system has none. Releases on PyPI ship prebuilt wheels for Linux (x86_64 and arm64, glibc 2.28+ and musl), macOS 11+ (Intel and Apple Silicon) and Windows x64, so no Rust toolchain or compiler is needed.

curl -LsSf https://astral.sh/uv/install.sh | sh   # Linux / macOS

Claude Code: MCP server + skills in one line

claude plugin marketplace add cheesejaguar/aerospace-mcp && claude plugin install aerospace-mcp@aerospace-mcp

Inside a session (Claude Code 2.1.275 or later) the same is /plugin install aerospace-mcp --marketplace cheesejaguar/aerospace-mcp. The plugin starts the MCP server with uvx aerospace-mcp and adds the skills in skills/. For the MCP server alone: claude mcp add aerospace -- uvx aerospace-mcp.

Skills for other agents (Cursor, Codex, OpenCode, ...)

npx skills add cheesejaguar/aerospace-mcp

The skills run tools through uvx --from aerospace-mcp aerospace-mcp-cli, so they need uv too (and Node.js for npx).

Claude Desktop and other MCP clients

{
  "mcpServers": {
    "aerospace": {
      "command": "uvx",
      "args": ["aerospace-mcp"]
    }
  }
}

GUI apps on macOS do not inherit your shell's PATH: if the client cannot find uvx, use the absolute path printed by which uvx (usually ~/.local/bin/uvx). The first launch downloads about 300 MB of dependencies; run uvx --from aerospace-mcp aerospace-mcp-cli list once beforehand so the client's server start-up timeout is not spent on the download.

CLI and HTTP API

uvx --from aerospace-mcp aerospace-mcp-cli run hohmann_transfer --r1_m 6778000 --r2_m 42164000
uvx --from aerospace-mcp aerospace-mcp-http        # http://localhost:8080/docs
uv tool install aerospace-mcp                      # all three commands on PATH

Optional extras work the same way, e.g. uvx --from 'aerospace-mcp[llm]' aerospace-mcp for the LLM agent tools (set LLM_TOOLS_ENABLED=true and OPENAI_API_KEY).

From source (development)

Building from a checkout compiles the native core, so it needs a Rust toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # Rust (rustup)
git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp
uv sync                               # builds aerospace_mcp._native

cp .env.example .env                  # optional: host/port/log level, LLM tools
uv run aerospace-mcp                  # MCP server (stdio)
uv run aerospace-mcp sse 0.0.0.0 8001 # MCP server (SSE, debugging)
uv run aerospace-mcp-http             # HTTP API
uvicorn main:app --reload --port 8080 # HTTP API with auto-reload

Docker

git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp
docker build -t aerospace-mcp .
docker run -p 8080:8080 aerospace-mcp

# Test the API
curl "http://localhost:8080/health"

📋 Table of Contents

• Features
• Installation
• Usage Examples
• Architecture
• FastMCP Migration
• Performance
• API Documentation
• MCP Integration
• Development
• Contributing
• License

✨ Features

Core Capabilities

• Airport Resolution: Intelligent city-to-airport mapping with 7,861 IATA airports worldwide
• Route Planning: Great-circle distance calculation with geodesic precision
• Performance Estimation: Aircraft-specific fuel and time calculations via OpenAP
• Atmospheric Modeling: ISA atmosphere profiles with optional enhanced precision
• Coordinate Transformations: ECEF, ECI, geodetic frame conversions for aerospace analysis
• Multiple Interfaces: HTTP REST API and Model Context Protocol (MCP) support
• Real-time Processing: Sub-second response times for flight planning requests

Space & Orbital Mechanics Capabilities

• 🛰️ Orbital Elements & State Vectors: Convert between Keplerian elements and Cartesian state vectors
• 🌍 Orbit Propagation: Numerical integration with J2 perturbations using RK4 method (native Rust core)
• 🗺️ Ground Track Computation: Calculate satellite ground tracks for mission planning
• 🔄 Hohmann Transfers: Calculate optimal two-impulse orbital transfers
• 🤝 Orbital Rendezvous: Plan multi-maneuver rendezvous sequences
• 🎯 Trajectory Optimization: Genetic algorithms and particle swarm optimization
• 📊 Uncertainty Analysis: Monte Carlo sampling for trajectory robustness assessment
• 🚀 Lambert Problem: Two-body trajectory determination for given time-of-flight (Izzo's 2015 algorithm, multi-revolution and retrograde; native Rust core)

Supported Operations

• ✅ Airport search by city name or IATA code
• ✅ Flight route planning with polyline generation
• ✅ Aircraft performance estimation (37 aircraft models via OpenAP)
• ✅ Fuel consumption and flight time calculations
• ✅ Great-circle distance calculations
• ✅ Multi-leg journey planning (plan_multi_leg_flight, 2-10 waypoints with aggregated totals)
• ✅ Wind-aware flight planning (optional headwind-adjusted cruise speed, time, and fuel)
• ✅ Aircraft database browsing and search (get_aircraft_database)
• ✅ Unit conversions (length, speed, mass, pressure, temperature, angle)
• ✅ Aircraft comparison analysis
• ✅ Atmospheric profile calculation (ISA standard atmosphere)
• ✅ Wind profile modeling (logarithmic/power law)
• ✅ Coordinate frame transformations (ECEF, ECI, geodetic)
• ✅ Wing aerodynamics analysis (VLM, lifting line theory)
• ✅ Airfoil polar generation and database access
• ✅ Aircraft stability derivatives calculation
• ✅ Propeller performance analysis (BEMT)
• ✅ UAV energy optimization and endurance estimation
• ✅ Motor-propeller matching analysis
• ✅ 3DOF rocket trajectory simulation with atmosphere integration
• ✅ Rocket sizing estimation for mission planning
• ✅ Launch angle optimization for maximum performance
• ✅ Thrust profile optimization using gradient descent
• ✅ Trajectory sensitivity analysis for design studies
• ✅ System capability discovery and status reporting
• ✅ Orbital mechanics calculations (Keplerian elements, state vectors, propagation)
• ✅ Ground track computation for satellite tracking and visualization
• ✅ Hohmann transfer planning for orbital maneuvers and mission design
• ✅ Orbital rendezvous planning for spacecraft proximity operations
• ✅ Trajectory optimization using genetic algorithms and particle swarm optimization
• ✅ Monte Carlo uncertainty analysis for trajectory robustness assessment
• ✅ Lambert problem solving for two-body trajectory determination
• ✅ Porkchop plot generation for interplanetary transfer opportunity analysis
• ✅ Optional SPICE integration with fallback to simplified ephemeris models
• ✅ Density altitude calculation for performance planning
• ✅ Airspeed conversions (IAS/CAS/EAS/TAS/Mach)
• ✅ Stall speed calculation for different configurations
• ✅ Weight and balance calculations with CG limits
• ✅ Takeoff/landing performance distance and V-speeds
• ✅ Fuel reserve calculation per FAR/ICAO regulations
• ✅ Kalman filter state estimation for sensor fusion
• ✅ LQR controller design for optimal control

Technical Features

• 🚀 Fast: In-memory airport database for microsecond lookups
• 🔧 Flexible: Pluggable backend system (currently OpenAP)
• 📊 Accurate: Uses WGS84 geodesic calculations
• 🌐 Standards: Follows ICAO aircraft codes and IATA airport codes
• 🔒 Reliable: Comprehensive error handling and graceful degradation
• 📚 Well-documented: Complete API documentation with examples
• ⚡ Hardware Optimized: NumPy vectorization with CuPy GPU acceleration support
• 🔄 Batch Processing: Vectorized operations for efficient bulk calculations
• 🔍 Tool Discovery: Dynamic tool search for finding relevant tools from 47 specialized tools plus 2 discovery tools

💾 Installation

System Requirements

• uv (recommended) or pip with Python 3.11+
• Prebuilt wheels: Linux x86_64/arm64 (glibc 2.28+ or musl 1.2+), macOS 11+ (Intel and Apple Silicon), Windows x64. Other platforms install from the source distribution, which needs a Rust toolchain.
• Disk: about 300 MB for the default install (about 500 MB with [llm])
• Network: for the first install; the airport database and aircraft models ship with the packages and work offline

With uv (no clone)

uvx aerospace-mcp                               # MCP server (stdio), run in place
uvx --from aerospace-mcp aerospace-mcp-cli list # any command, run in place
uv tool install aerospace-mcp                   # install the commands on PATH
uv tool upgrade aerospace-mcp                   # later: upgrade

uvx caches the environment after the first run. To pick up a new release with uvx, run uvx aerospace-mcp@latest once.

With pip

python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip                  # old pips miss the manylinux_2_28 / musllinux wheels
pip install aerospace-mcp                            # or 'aerospace-mcp[llm]', 'aerospace-mcp[all]'
aerospace-mcp-cli list

Extras: llm (LLM agent tools), atmosphere, aircraft, rockets, space, gnc, all.

From source

See From source (development): uv sync (or pip install -e .) in a checkout, with Rust installed via rustup.

Docker

git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp
docker build -t aerospace-mcp .
docker run -d -p 8080:8080 --name aerospace-mcp aerospace-mcp
curl http://localhost:8080/health

The image builds the native core itself (Rust is installed in the build stage only) and includes the llm extra.

Troubleshooting Installation

The MCP client cannot start the server / uvx: command not found: GUI apps (Claude Desktop on macOS in particular) do not see the PATH from your shell profile. Put the absolute path from which uvx in the command field.

The MCP client times out on first launch: the first uvx run downloads the dependencies. Run uvx --from aerospace-mcp aerospace-mcp-cli list once in a terminal, then restart the client.

error: can't find Rust compiler / Failed to build aerospace-mcp: the installer found no wheel for your platform and fell back to the source distribution. Upgrade pip (python -m pip install --upgrade pip); if your platform has no prebuilt wheel (see above), install Rust with curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh and retry.

LLM agent tools report that LiteLLM is not installed: install the llm extra (pip install 'aerospace-mcp[llm]', or uvx --from 'aerospace-mcp[llm]' aerospace-mcp).

Check an installation:

aerospace-mcp-cli run get_system_status   # optional packages and their versions
aerospace-mcp-cli run hohmann_transfer --r1_m 6778000 --r2_m 42164000

🎯 Usage Examples

HTTP API Examples

Basic Flight Planning

# Plan a simple flight
curl -X POST "http://localhost:8080/plan" \
  -H "Content-Type: application/json" \
  -d '{
    "depart_city": "San Francisco",
    "arrive_city": "New York",
    "ac_type": "A320",
    "cruise_alt_ft": 37000,
    "backend": "openap"
  }'

Airport Search

# Find airports by city
curl "http://localhost:8080/airports/by_city?city=Tokyo"

# Filter by country
curl "http://localhost:8080/airports/by_city?city=London&country=GB"

# Multiple results
curl "http://localhost:8080/airports/by_city?city=Paris"

Advanced Flight Planning

# Specify exact airports and aircraft mass
curl -X POST "http://localhost:8080/plan" \
  -H "Content-Type: application/json" \
  -d '{
    "depart_city": "Los Angeles",
    "arrive_city": "Tokyo",
    "prefer_depart_iata": "LAX",
    "prefer_arrive_iata": "NRT",
    "ac_type": "B777",
    "cruise_alt_ft": 39000,
    "mass_kg": 220000,
    "route_step_km": 100.0,
    "backend": "openap"
  }'

Python Client Examples

Simple Client

import requests
import json

class AerospaceClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url

    def plan_flight(self, departure, arrival, aircraft="A320", altitude=35000):
        """Plan a flight between two cities."""
        response = requests.post(f"{self.base_url}/plan", json={
            "depart_city": departure,
            "arrive_city": arrival,
            "ac_type": aircraft,
            "cruise_alt_ft": altitude,
            "backend": "openap"
        })
        return response.json()

    def find_airports(self, city, country=None):
        """Find airports in a city."""
        params = {"city": city}
        if country:
            params["country"] = country
        response = requests.get(f"{self.base_url}/airports/by_city", params=params)
        return response.json()

# Usage
client = AerospaceClient()

# Find airports
airports = client.find_airports("Sydney", "AU")
print(f"Sydney has {len(airports)} airports")

# Plan flight
plan = client.plan_flight("Sydney", "Melbourne", "B737")
print(f"Flight distance: {plan['distance_nm']:.0f} NM")
print(f"Flight time: {plan['estimates']['block']['time_min']:.0f} minutes")

Batch Processing

import asyncio
import aiohttp
from typing import List, Dict

async def plan_multiple_flights(flights: List[Dict]) -> List[Dict]:
    """Plan multiple flights concurrently."""
    async with aiohttp.ClientSession() as session:
        tasks = []
        for flight in flights:
            task = plan_single_flight(session, flight)
            tasks.append(task)

        results = await asyncio.gather(*tasks, return_exceptions=True)
        return results

async def plan_single_flight(session, flight_data):
    """Plan a single flight."""
    async with session.post(
        "http://localhost:8080/plan",
        json=flight_data
    ) as response:
        return await response.json()

# Example usage
flights_to_plan = [
    {"depart_city": "New York", "arrive_city": "London", "ac_type": "A330"},
    {"depart_city": "London", "arrive_city": "Dubai", "ac_type": "B777"},
    {"depart_city": "Dubai", "arrive_city": "Singapore", "ac_type": "A350"}
]

# Run the batch planning
results = asyncio.run(plan_multiple_flights(flights_to_plan))
for i, result in enumerate(results):
    if not isinstance(result, Exception):
        print(f"Flight {i+1}: {result['distance_nm']:.0f} NM, {result['estimates']['block']['time_min']:.0f} min")

Orbital Mechanics Examples

Python Examples

import requests

class OrbitalMechanicsClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url

    def plan_hohmann_transfer(self, r1_km, r2_km):
        """Calculate Hohmann transfer between two circular orbits."""
        response = requests.post(f"{self.base_url}/hohmann_transfer", json={
            "r1_m": r1_km * 1000,  # Convert to meters
            "r2_m": r2_km * 1000
        })
        return response.json()

    def propagate_satellite_orbit(self, elements, duration_hours):
        """Propagate satellite orbit with J2 perturbations."""
        response = requests.post(f"{self.base_url}/propagate_orbit_j2", json={
            "initial_state": elements,
            "propagation_time_s": duration_hours * 3600,
            "time_step_s": 300  # 5-minute steps
        })
        return response.json()

# Example usage
client = OrbitalMechanicsClient()

# Plan a GTO to GEO transfer
gto_alt = 200    # km (perigee)
geo_alt = 35786  # km (GEO altitude)

transfer = client.plan_hohmann_transfer(
    6378 + gto_alt,  # Earth radius + altitude
    6378 + geo_alt
)

print(f"Transfer Delta-V: {transfer['delta_v_total_ms']/1000:.2f} km/s")
print(f"Transfer Time: {transfer['transfer_time_h']:.1f} hours")

# Propagate ISS orbit for one day
iss_elements = {
    "semi_major_axis_m": 6793000,  # ~415 km altitude
    "eccentricity": 0.0001,
    "inclination_deg": 51.6,
    "raan_deg": 0.0,
    "arg_periapsis_deg": 0.0,
    "true_anomaly_deg": 0.0,
    "epoch_utc": "2024-01-01T12:00:00"
}

orbit_states = client.propagate_satellite_orbit(iss_elements, 24)
print(f"Propagated {len(orbit_states)} orbital states over 24 hours")

Trajectory Optimization Example

# Optimize a lunar transfer trajectory
def optimize_lunar_transfer():
    initial_trajectory = [
        {
            "time_s": 0,
            "position_m": [6700000, 0, 0],      # LEO
            "velocity_ms": [0, 7500, 0]
        },
        {
            "time_s": 86400 * 3,  # 3 days
            "position_m": [384400000, 0, 0],    # Moon distance
            "velocity_ms": [0, 1000, 0]
        }
    ]

    response = requests.post("http://localhost:8080/genetic_algorithm_optimization", json={
        "initial_trajectory": initial_trajectory,
        "objective": "minimize_delta_v",
        "constraints": {
            "max_thrust_n": 50000,
            "max_acceleration_ms2": 10
        }
    })

    result = response.json()
    print(f"Optimized Delta-V: {result['total_delta_v_ms']/1000:.2f} km/s")
    print(f"Flight Time: {result['flight_time_s']/86400:.1f} days")
    return result

optimized_trajectory = optimize_lunar_transfer()

# Generate porkchop plot for Mars mission planning
def plan_mars_mission():
    response = requests.post("http://localhost:8080/porkchop_plot_analysis", json={
        "departure_body": "Earth",
        "arrival_body": "Mars",
        "min_tof_days": 200,
        "max_tof_days": 300
    })

    analysis = response.json()

    if analysis["summary_statistics"]["feasible_transfers"] > 0:
        optimal = analysis["optimal_transfer"]
        print(f"Optimal Mars Transfer:")
        print(f"  Launch: {optimal['departure_date']}")
        print(f"  Arrival: {optimal['arrival_date']}")
        print(f"  C3: {optimal['c3_km2_s2']:.2f} km²/s²")
        print(f"  Flight Time: {optimal['time_of_flight_days']:.0f} days")
    else:
        print("No feasible transfers found in date range")

plan_mars_mission()

JavaScript/TypeScript Examples

interface FlightPlan {
  depart_city: string;
  arrive_city: string;
  ac_type: string;
  cruise_alt_ft?: number;
  backend: "openap";
}

class AerospaceAPI {
  constructor(private baseUrl: string = "http://localhost:8080") {}

  async planFlight(request: FlightPlan) {
    const response = await fetch(`${this.baseUrl}/plan`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(request),
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.statusText}`);
    }

    return await response.json();
  }

  async findAirports(city: string, country?: string) {
    const params = new URLSearchParams({ city });
    if (country) params.append("country", country);

    const response = await fetch(`${this.baseUrl}/airports/by_city?${params}`);
    return await response.json();
  }
}

// Usage
const api = new AerospaceAPI();

try {
  const plan = await api.planFlight({
    depart_city: "Boston",
    arrive_city: "Seattle",
    ac_type: "B737",
    cruise_alt_ft: 36000,
    backend: "openap"
  });

  console.log(`Flight planned: ${plan.distance_nm} NM`);
  console.log(`Estimated time: ${plan.estimates.block.time_min} minutes`);
} catch (error) {
  console.error("Flight planning failed:", error);
}

🏗️ Architecture

System Overview

graph TB
    Users[Users/Clients] --> API[FastAPI REST API]
    Users --> MCP[MCP Server]

    API --> Core[Core Services]
    MCP --> Core

    subgraph "Core Services"
        Airport[Airport Resolution]
        Route[Route Calculation]
        Perf[Performance Estimation]
    end

    subgraph "Data Sources"
        AirportDB[Airport Database<br/>7,861 IATA airports]
        OpenAP[OpenAP Models<br/>37 aircraft]
        Geodesic[GeographicLib<br/>WGS84 calculations]
    end

    Airport --> AirportDB
    Route --> Geodesic
    Perf --> OpenAP

Key Components

1. FastAPI Application (main.py)

   • RESTful endpoints for HTTP clients
   • Auto-generated OpenAPI documentation
   • Request/response validation with Pydantic

2. MCP Server (aerospace_mcp/fastmcp_server.py)

   • Model Context Protocol implementation via FastMCP
   • Tool-based interface for AI assistants
   • Async request handling

3. Core Services

   • Airport Resolution: City → Airport mapping with intelligent selection
   • Route Calculation: Great-circle paths with polyline generation
   • Performance Estimation: OpenAP-based fuel and time calculations

4. Data Layer

   • In-memory Airport Database: 7,861 IATA airports loaded at startup
   • OpenAP Integration: Aircraft performance models
   • GeographicLib: Precise geodesic calculations

5. Native Core (rust/, imported as aerospace_mcp._native)

   • Rust + PyO3 extension for the numerically heavy code: 3-DOF rocket simulation and performance analysis, the launch-angle and thrust-profile optimizers, Kepler / element conversions, J2 orbit propagation, ground tracks, Hohmann transfers, and Izzo's Lambert solver
   • Optimizers evaluate every candidate trajectory natively (no Python call per evaluation), roughly 190x faster than the former pure-Python loop; the MCP server, tool wrappers and data models remain Python

Design Principles

• Performance First: In-memory data structures for sub-millisecond lookups
• Graceful Degradation: Works without optional dependencies
• Type Safety: Full type hints and Pydantic validation
• Extensible: Plugin architecture for new backends
• Standards Compliant: ICAO, IATA, and OpenAP standards
• Hardware Agnostic: NumPy/CuPy abstraction for CPU/GPU flexibility

🚀 FastMCP Migration

This project has been migrated from the traditional MCP SDK to FastMCP, providing significant improvements in developer experience and code maintainability.

What is FastMCP?

FastMCP is a high-level, Pythonic framework for building Model Context Protocol servers. It dramatically reduces boilerplate code while maintaining full MCP compatibility.

Migration Benefits

✅ 70% Less Code: Tool definitions went from verbose JSON schemas to simple Python decorators ✅ Better Type Safety: Automatic schema generation from type hints ✅ Cleaner Architecture: Modular tool organization across logical domains ✅ Improved Maintainability: Pythonic code that's easier to read and extend ✅ Full Compatibility: Same MCP protocol, works with all existing clients

Before vs After

Before (Traditional MCP SDK):

Tool(
    name="search_airports",
    description="Search for airports by IATA code or city name",
    inputSchema={
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "IATA code or city name"},
            "country": {"type": "string", "description": "Optional country filter"},
            "query_type": {"type": "string", "enum": ["iata", "city", "auto"]}
        },
        "required": ["query"]
    }
)

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict):
    if name == "search_airports":
        return await _handle_search_airports(arguments)
    # ... 40+ more tool handlers

After (FastMCP):

@mcp.tool
def search_airports(
    query: str,
    country: str | None = None,
    query_type: Literal["iata", "city", "auto"] = "auto"
) -> str:
    """Search for airports by IATA code or city name."""
    # Implementation here

Architecture Improvements

The FastMCP refactoring introduced a modular architecture with tools organized by domain:

• tools/core.py - Core flight planning (search, plan, distance, performance)
• tools/atmosphere.py - Atmospheric modeling and wind analysis
• tools/frames.py - Coordinate frame transformations
• tools/aerodynamics.py - Wing analysis and airfoil polars
• tools/propellers.py - Propeller BEMT and UAV energy analysis
• tools/rockets.py - Rocket trajectory and sizing
• tools/orbits.py - Orbital mechanics and propagation
• tools/optimization.py - Trajectory optimization algorithms

Integration modules with NumPy vectorization:

• integrations/_array_backend.py - NumPy/CuPy abstraction layer for GPU support
• integrations/atmosphere.py - Vectorized ISA atmosphere calculations
• integrations/aero.py - Vectorized aerodynamics computations
• integrations/rockets.py - Vectorized trajectory integration
• integrations/frames.py - Vectorized coordinate transformations

Compatibility Notes

• Entry Point: Now uses aerospace_mcp.fastmcp_server:run
• Dependencies: Includes fastmcp>=2.11.3 instead of raw mcp
• Server Name: Still aerospace-mcp for client compatibility
• All Tools: All 47 tools maintain exact same names and parameters

⚙️ Configuration (.env)

Both the HTTP server and MCP servers automatically load environment variables from a local .env (via python-dotenv).

• AEROSPACE_MCP_MODE: http or mcp (Docker entrypoint switch)
• AEROSPACE_MCP_HOST: Bind host for HTTP (default 0.0.0.0)
• AEROSPACE_MCP_PORT: Port for HTTP (default 8080)
• AEROSPACE_MCP_LOG_LEVEL: debug|info|warning|error (default info)
• AEROSPACE_MCP_ENV: development|production (controls reload)
• LLM_TOOLS_ENABLED: true|false to enable AI agent tools (default false)
• OPENAI_API_KEY: Required if LLM tools are enabled

HTTP API hardening (the FastAPI app in main.py is a thin layer over aerospace_mcp/core.py):

• CORS_ORIGINS: Comma-separated list of allowed origins; CORS is disabled when unset
• RATE_LIMIT_RPM: Per-IP requests per minute (default 120, 0 disables rate limiting)
• MAX_BODY_BYTES: Maximum accepted request body size (default 1 MiB)

Example .env:

AEROSPACE_MCP_MODE=http
AEROSPACE_MCP_HOST=0.0.0.0
AEROSPACE_MCP_PORT=8080
AEROSPACE_MCP_LOG_LEVEL=debug
LLM_TOOLS_ENABLED=false
# OPENAI_API_KEY=sk-...

⚡ Performance

Benchmarks

Optimization Tips

1. Route Resolution: Use larger route_step_km values for faster processing
2. Caching: Implement client-side caching for repeated requests
3. Batch Processing: Use async clients for multiple concurrent requests
4. Memory: Increase available RAM for better OpenAP performance

Scaling Considerations

• Horizontal Scaling: Stateless design allows multiple instances
• Load Balancing: Standard HTTP load balancers work well
• Database: Consider external database for airport data at scale
• Caching: Add Redis for shared cache across instances

GPU Acceleration (CuPy)

The aerospace calculations are optimized using NumPy's vectorized operations, with a drop-in CuPy backend for GPU acceleration on CUDA-capable hardware.

Enabling GPU Acceleration

# In your code, before using aerospace functions:
from aerospace_mcp.integrations._array_backend import set_backend, get_backend_info

# Check available backends
print(get_backend_info())
# {'current_backend': 'numpy', 'numpy_available': True, 'cupy_available': True, ...}

# Switch to GPU (requires CuPy and CUDA)
set_backend('cupy')

# Switch back to CPU
set_backend('numpy')

Installing CuPy

# For CUDA 11.x
pip install cupy-cuda11x

# For CUDA 12.x
pip install cupy-cuda12x

# Auto-detect CUDA version
pip install cupy

Modules with GPU Support

The following integration modules support GPU acceleration via the array backend:

Note: GPU acceleration provides the most benefit for batch operations with 1000+ data points. For single calculations, CPU (NumPy) is typically faster due to GPU transfer overhead.

📖 API Documentation

Interactive Documentation

When running the server, comprehensive API documentation is available at:

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc
• OpenAPI Schema: http://localhost:8080/openapi.json

Core Endpoints

GET /health

Health check and system status.

Response:

{
  "status": "ok",
  "openap": true,
  "airports_count": 7861
}

GET /airports/by_city

Search airports by city name.

Parameters:

• city (required): City name to search
• country (optional): ISO country code filter

Example: GET /airports/by_city?city=London&country=GB

POST /plan

Generate complete flight plan.

Request Body:

{
  "depart_city": "San Francisco",
  "arrive_city": "New York",
  "ac_type": "A320",
  "cruise_alt_ft": 37000,
  "mass_kg": 65000,
  "route_step_km": 25.0,
  "backend": "openap"
}

Response: Complete flight plan with route polyline and performance estimates.

Error Handling

All endpoints return standard HTTP status codes:

• 200: Success
• 400: Bad Request (invalid parameters)
• 404: Not Found (airport/city not found)
• 501: Not Implemented (backend unavailable)

Error responses include detailed messages:

{
  "detail": "departure: IATA 'XYZ' not found."
}

🤖 MCP Integration

Supported MCP Clients

• Claude Desktop: Native integration
• VS Code Continue: Plugin support
• Custom Clients: Standard MCP protocol

Available Tools

Claude Desktop Setup

1. Open Claude Desktop Settings
2. Add server configuration:

{
  "mcpServers": {
    "aerospace": {
      "command": "uvx",
      "args": ["aerospace-mcp"]
    }
  }
}

From a source checkout use "command": "uv" with "args": ["--directory", "/path/to/aerospace-mcp", "run", "aerospace-mcp"]. If Claude Desktop cannot find uvx, give its absolute path (which uvx).

3. Restart Claude Desktop
4. Test with: "Search for airports in Tokyo"

Tool Discovery

With 47 specialized aerospace tools available (plus 2 discovery tools), the MCP server includes a tool search tool following Anthropic's guide for dynamic tool discovery:

# Search by natural language
search_aerospace_tools("atmospheric pressure altitude")
# Returns: get_atmosphere_profile, wind_model_simple, ...

# Search by regex pattern
search_aerospace_tools("(?i)orbit", search_type="regex")
# Returns: propagate_orbit_j2, elements_to_state_vector, hohmann_transfer, ...

# Filter by category
search_aerospace_tools("calculate", category="orbits")
# Returns only orbital mechanics tools matching "calculate"

# List all categories
list_tool_categories()
# Returns: core, atmosphere, frames, aerodynamics, propellers, rockets, orbits, gnc, performance, optimization, agents

Available categories:

• core: Flight planning, airports, distance, aircraft performance
• atmosphere: ISA profiles, wind modeling
• frames: Coordinate transformations (ECEF, ECI, geodetic)
• aerodynamics: Wing analysis, airfoil polars, stability derivatives
• propellers: BEMT analysis, UAV energy estimation
• rockets: 3DOF trajectory, sizing, launch optimization
• orbits: Orbital elements, propagation, transfers, rendezvous, Lambert solver
• optimization: GA, PSO, Monte Carlo, porkchop plots
• gnc: Kalman filter state estimation, LQR controller design
• performance: Density altitude, airspeed conversion, stall speeds, W&B, takeoff/landing
• agents: LLM-powered tool selection and data formatting

Deferred Tool Loading

For applications with many tools, aerospace-mcp supports deferred tool loading to keep context windows efficient. When using the Anthropic API with MCP, configure your mcp_toolset to defer loading of all tools except the discovery tools:

{
  "tools": [
    {
      "type": "tool_search_tool_regex_20251119",
      "name": "tool_search_tool_regex"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "aerospace-mcp",
      "default_config": {
        "defer_loading": true
      },
      "configs": {
        "search_aerospace_tools": { "defer_loading": false },
        "list_tool_categories": { "defer_loading": false }
      }
    }
  ]
}

This configuration:

1. Loads discovery tools immediately (search_aerospace_tools, list_tool_categories)
2. Defers all other tools until Claude searches for them
3. Automatically expands tool_reference blocks from search results into full definitions

When Claude needs a specific tool, it uses search_aerospace_tools which returns tool_reference blocks:

{
  "tool_references": [
    { "type": "tool_reference", "tool_name": "hohmann_transfer" },
    { "type": "tool_reference", "tool_name": "propagate_orbit_j2" }
  ]
}

The API automatically expands these references into full tool definitions, keeping context efficient while providing access to all 47 tools.

VS Code Continue Setup

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "aerospace-mcp",
      "command": "uv",
      "args": ["run", "aerospace-mcp"],
      "workingDirectory": "/path/to/aerospace-mcp"
    }
  ]
}

🛠️ Development

Development Setup

# Clone and setup
git clone https://github.com/cheesejaguar/aerospace-mcp.git
cd aerospace-mcp

# Create the development environment (needs Rust, see Quick Start)
uv sync
source .venv/bin/activate

# Install pre-commit hooks
pre-commit install

# Run development server
uvicorn main:app --reload --log-level debug

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test file
pytest tests/test_plan.py -v

# Run tool-specific tests
pytest tests/tools/ -v

# Native core unit tests (no Python needed)
cd rust && cargo test --no-default-features

After editing Rust sources, uv sync (or uv run ...) rebuilds the extension automatically; with a plain pip setup run pip install -e . again.

Code Quality

# Format code
black . && isort .

# Type checking
mypy main.py aerospace_mcp/

# Linting
ruff check .

# Rust formatting and lints
(cd rust && cargo fmt --check && cargo clippy --no-default-features --all-targets -- -D warnings)

# Pre-commit (runs all checks)
pre-commit run --all-files

Project Structure

aerospace-mcp/
├── main.py                 # FastAPI application
├── aerospace_mcp/          # MCP server implementation
│   ├── __init__.py
│   ├── fastmcp_server.py  # FastMCP server entry point
│   ├── core.py            # Shared business logic
│   ├── tools/             # MCP tool definitions
│   │   ├── core.py        # Flight planning tools
│   │   ├── atmosphere.py  # Atmospheric modeling tools
│   │   ├── aerodynamics.py # Wing & airfoil analysis
│   │   ├── frames.py      # Coordinate transformations
│   │   ├── rockets.py     # Rocket trajectory tools
│   │   ├── orbits.py      # Orbital mechanics tools
│   │   ├── propellers.py  # Propeller analysis tools
│   │   ├── optimization.py # Trajectory optimization
│   │   ├── gnc.py         # GNC tools (Kalman filter, LQR)
│   │   ├── performance.py # Aircraft performance tools
│   │   ├── agents.py      # LLM-powered agent tools
│   │   └── tool_search.py # Tool discovery and search
│   └── integrations/      # Backend computation modules
│       ├── _array_backend.py # NumPy/CuPy abstraction (GPU support)
│       ├── atmosphere.py  # Vectorized ISA calculations
│       ├── aero.py        # Vectorized aerodynamics
│       ├── frames.py      # Vectorized coordinate transforms
│       ├── rockets.py     # Rocket data model (simulation in rust/)
│       ├── trajopt.py     # Trajectory optimization (optimizers in rust/)
│       ├── orbits.py      # Orbital mechanics (kernels in rust/)
│       └── propellers.py  # Propeller BEMT analysis
├── rust/                  # Native core (Rust + PyO3 -> aerospace_mcp._native)
│   ├── Cargo.toml
│   └── src/
│       ├── rocket.rs      # 3-DOF ascent simulation & performance metrics
│       ├── optimize.rs    # Golden-section, gradient descent, rocket optimizers
│       ├── orbit.rs       # Kepler, elements <-> state, J2 RK4, ground track
│       ├── lambert.rs     # Izzo Lambert solver
│       └── python.rs      # PyO3 bindings
├── app/                   # Alternative FastAPI structure
│   ├── __init__.py
│   └── main.py
├── tests/                 # Test suite
│   ├── conftest.py
│   ├── test_airports.py
│   ├── test_plan.py
│   ├── test_fastmcp.py
│   ├── test_integrations_*.py  # Integration module tests
│   └── tools/             # Tool-specific tests
│       ├── test_tools_performance.py  # Performance tools tests
│       ├── test_tools_gnc.py          # GNC tools tests
│       └── test_tools_lambert.py      # Lambert solver tests
├── docs/                  # Documentation
│   ├── API.md
│   ├── ARCHITECTURE.md
│   ├── INTEGRATION.md
│   ├── QUICKSTART.md
│   ├── DEPLOYMENT.md
│   └── MCP_INTEGRATION.md
├── pyproject.toml         # Project configuration
├── requirements.txt       # Dependencies
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Multi-service setup
└── README.md             # This file

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines.

Quick Contributing Guide

1. Fork & Clone

   git clone https://github.com/yourusername/aerospace-mcp.git
   cd aerospace-mcp
   

2. Setup Development Environment

   uv sync && source .venv/bin/activate
   

3. Make Changes

   • Add features or fix bugs
   • Write tests for new functionality
   • Update documentation as needed

4. Test & Format

   pytest
   black . && isort .
   mypy main.py
   

5. Submit Pull Request

   • Clear title and description
   • Reference any related issues
   • Ensure CI/CD checks pass

Areas for Contribution

• New Aircraft Support: Add more aircraft types to OpenAP
• Weather Integration: Add weather data sources
• Route Optimization: Wind-optimal routing beyond the built-in multi-leg planner (plan_multi_leg_flight)
• UI/Frontend: Web interface for flight planning
• Database Backend: PostgreSQL/MongoDB integration
• Performance: Optimization and caching improvements
• GPU Optimization: Extend CuPy support to additional modules
• Vectorization: Improve NumPy vectorization coverage

📚 Documentation

Complete Documentation

• Quick Start Guide - Get up and running in 5 minutes
• API Reference - Complete REST API documentation
• MCP Integration - Model Context Protocol setup
• Architecture Guide - System design and components
• Deployment Guide - Production deployment strategies
• Contributing Guide - Development and contribution guidelines
• Integration Guide - Client integration examples

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Acknowledgments

• OpenAP: Aircraft performance modeling - TU Delft
• AirportsData: Airport database - mborsetti
• GeographicLib: Geodesic calculations - Charles Karney
• FastAPI: Modern web framework - Sebastián Ramírez

🆘 Support & Community

Getting Help

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and community support
• Documentation: Comprehensive guides in /docs
• Examples: Code examples and tutorials

Community

• Discord: WIP for real-time chat

Professional Support

For enterprise support, consulting, or custom development:

• Email: hello@aeroastro.org
• Website: https://aeroastro.org

⭐ Star this repository if you find it useful!

Built with ❤️ for the aviation and software development communities.