VATSIM MCP Server

A Model Context Protocol (MCP) server for VATSIM flight tracking data with enhanced analytics and sorting capabilities.

Features

• Real-time VATSIM Data: Access live flight and ATC controller information
• Enhanced Analytics: Sort and filter pilots by groundspeed, altitude, heading, and more
• No Limits: Query all online pilots (1000+) instead of being limited to 20
• Smart Sorting: Find fastest aircraft, highest altitude flights, newest connections
• Mapping Integration: Send callsigns to mapping servers for visualization
• Dual Runtime: Works with both Node.js and Bun

Installation

npm install -g vatsim-mcp-server

Or with Bun:

bun install -g vatsim-mcp-server

Usage

Command Line

# Using npm/node
vatsim-mcp-server

# Using bun directly
bun vatsim-mcp-server

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "vatsim": {
      "command": "vatsim-mcp-server"
    }
  }
}

Or with Bun:

{
  "mcpServers": {
    "vatsim": {
      "command": "bun",
      "args": ["vatsim-mcp-server"]
    }
  }
}

Available Tools

get_vatsim_pilots

Get online VATSIM pilots with powerful filtering and sorting.

Parameters:

• callsign (string): Filter by callsign
• departure (string): Filter by departure airport (e.g., "EDDF")
• arrival (string): Filter by arrival airport (e.g., "KJFK")
• aircraft (string): Filter by aircraft type (e.g., "B738")
• limit (number): Max results (default: 50, max: 2000, 0 = all)
• get_all (boolean): Return all pilots regardless of limit
• sort_by (string): Sort by "groundspeed", "altitude", "heading", "callsign", "logon_time"
• sort_order (string): "asc" or "desc" (default: "desc")

Examples:

// Find fastest aircraft
{ "sort_by": "groundspeed", "sort_order": "desc", "limit": 5 }

// Get all flights from Frankfurt
{ "departure": "EDDF", "get_all": true }

// Find highest altitude flights
{ "sort_by": "altitude", "sort_order": "desc", "limit": 10 }

find_vatsim_flight

Find specific flight by callsign with detailed information.

get_airport_traffic

Get all departures and arrivals for a specific airport.

get_flights_in_area

Get flights within a geographic radius.

get_vatsim_controllers

Get online ATC controllers.

get_vatsim_stats

Get VATSIM network statistics.

send_callsigns_to_map

Send aircraft callsigns to mapping MCP server for visualization.

Enhanced Analytics

The v2.0 update removes the previous 20-pilot limit and adds powerful sorting capabilities:

• Query all pilots: Get complete dataset of 1000+ online pilots
• Smart sorting: Find extremes (fastest, highest, newest)
• Statistical insights: Automatic speed/altitude ranges for analytical queries
• Mapping ready: All results include callsigns for map visualization

Example Queries

"Which flight has the highest airspeed?"

{
  "sort_by": "groundspeed",
  "sort_order": "desc", 
  "limit": 1
}

"Show all flights above FL400"

{
  "get_all": true
}

(Then filter results by altitude)

"Top 10 most recently connected pilots"

{
  "sort_by": "logon_time",
  "sort_order": "desc",
  "limit": 10
}

Development

# Clone and install
git clone <repository>
cd vatsim-mcp-server
npm install

# Development with hot reload
npm run dev

# Build for distribution
npm run build

# Test functionality  
npm test

Requirements

• Node.js 18+ or Bun 1.0+
• Internet connection for VATSIM API access

License

MIT

Data Source

This server uses the official VATSIM data feed: https://data.vatsim.net/v3/vatsim-data.json

Data is cached for 30 seconds to minimize API load while providing near real-time information.