Mapping MCP Server

A Model Context Protocol (MCP) server for interactive map visualization with real-time VATSIM aircraft tracking, featuring WebSocket updates and custom aircraft icons.

Features

• Interactive Web Map: Leaflet-based map with pan, zoom, and object interaction
• Real-time VATSIM Integration: Fetch and display live aircraft data from VATSIM
• WebSocket Updates: Live map updates without page refresh
• Custom Aircraft Icons: Rotatable aircraft icons showing heading direction
• Multi-Object Support: Display aircraft, controllers, airports, and waypoints
• Flexible Data Input: Accept callsigns or full position data
• Auto Port Selection: Automatically finds available port if 3001 is in use
• React 19 & TypeScript: Modern tech stack with full type safety

Installation

npm install -g mapping-mcp-server

Or with Bun:

bun install -g mapping-mcp-server

Usage

Command Line

# Using npm/node
mapping-mcp-server

# Using bun directly
bun mapping-mcp-server

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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

Or with Bun:

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

Available Tools

show_map

Display geo-located objects on an interactive map.

Parameters:

• topic (string): Title for the map display
• objects (array): Array of geo-located objects with:
  • latitude (number): Required
  • longitude (number): Required
  • type (string): "aircraft", "controller", "airport", or "waypoint"
  • callsign (string): Object identifier
  • altitude (number): Altitude in feet
  • heading (number): Direction in degrees (0-360)
  • groundspeed (number): Speed in knots
  • Additional fields as needed

Example:

{
  "topic": "European Traffic",
  "objects": [
    {
      "callsign": "DLH123",
      "latitude": 50.0264,
      "longitude": 8.5431,
      "altitude": 35000,
      "heading": 270,
      "groundspeed": 420,
      "type": "aircraft",
      "aircraft": "A320",
      "departure": "EDDF",
      "arrival": "EGLL"
    }
  ]
}

show_aircraft_by_callsigns

Display aircraft by fetching real-time VATSIM data using callsigns.

Parameters:

• callsigns (array): Array of aircraft callsigns
• topic (string): Optional map title
• center (object): Optional center point with latitude, longitude, radius

Example:

{
  "callsigns": ["DLH123", "SAS456", "KLM789"],
  "topic": "Selected VATSIM Flights"
}

open_map

Open the mapping interface in a browser window.

clear_map

Clear all objects from the current map display.

Integration with VATSIM MCP

The mapping server works seamlessly with the VATSIM MCP server:

1. VATSIM queries: Use vatsim-mcp to search for flights
2. Send to map: VATSIM MCP sends callsigns to mapping server
3. Data fetch: Mapping server fetches complete data from VATSIM API
4. Display: Aircraft appear on map with real-time positions

Web Interface Features

The web interface at http://localhost:3001 provides:

• Interactive Map: Pan, zoom, and click on objects
• Aircraft Icons: Rotatable emoji icons showing heading
• Popup Details: Click any object for full information
• Real-time Updates: WebSocket connection for live updates
• Auto-centering: Map centers on displayed objects
• Legend: Shows object counts by type

API Endpoints

• GET / - Main map interface
• GET /api/data - Current map data as JSON
• POST /api/show-aircraft-by-callsigns - Display aircraft by callsigns
• WS /ws - WebSocket for real-time updates

Development

# Clone repository
git clone <repository>
cd mapping-mcp-server

# Install dependencies
bun install

# Development with hot reload
bun run dev

# Build for distribution
npm run build

# Run tests
npm test

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Claude     │────▶│  VATSIM MCP  │────▶│ Mapping MCP  │
│   Desktop    │     │    Server    │     │    Server    │
└──────────────┘     └──────────────┘     └──────────────┘
                            │                      │
                            ▼                      ▼
                     ┌──────────────┐      ┌──────────────┐
                     │  VATSIM API  │      │  Web Browser │
                     └──────────────┘      │   (Leaflet)  │
                                           └──────────────┘

Performance

• Caching: 30-second cache for VATSIM data
• Bundling: Frontend bundled on-the-fly with Bun
• WebSocket: Efficient real-time updates
• Port Management: Automatic port selection if default is busy

Troubleshooting

Blank Map Page

• Check browser console for errors
• Verify frontend.tsx is being bundled correctly
• Ensure Leaflet CSS is loading

Connection Issues

• Default port is 3001, automatically increments if busy
• Check firewall settings for localhost connections
• Verify WebSocket connection in browser DevTools

VATSIM Data Not Loading

• Check internet connection
• Verify VATSIM API is accessible
• Check for rate limiting (30-second cache)

Requirements

• Node.js 18+ or Bun 1.0+
• Modern web browser with JavaScript enabled
• Internet connection for VATSIM data

License

MIT

Data Sources

• VATSIM API: https://data.vatsim.net/v3/vatsim-data.json
• Map Tiles: OpenStreetMap via Leaflet
• Icons: Native emoji for aircraft and markers

Contributing

Contributions welcome! Please submit PRs or issues on GitHub.

Changelog

v1.0.0

• Initial release with full VATSIM integration
• WebSocket real-time updates
• Custom aircraft icons with heading
• Support for npm and Bun runtimes