Airplane.Live MCP Server

MCP server that connects to the Airplanes.live API to provide real-time flight and aircraft data for analysis or visualization.

This MCP server integrates with theairplanes.live APIto provide real-time aircraft tracking capabilities to Claude Desktop. Track flights, find aircraft by callsign, registration, or position - all directly from Claude!

📖 Educational and Non-Commercial Use Only

This project uses theairplanes.live APIwhich is provided foreducational and non-commercial purposes only. Please respect their terms of service.

This project does NOT intend to replace or compete with the officialairplanes.live globe viewer.The official globe is the primary and recommended way to visualize flight data. This MCP server is designed as a complementary educational tool for Claude Desktop integration and MCP development learning.

📖Full API Terms:https://airplanes.live/api-guide/
🌍Official Globe Viewer:https://globe.airplanes.live

graph TD A[Claude Desktop] --> B[MCP Protocol] B --> C[airplane_server.py] C --> D[API Functions] D --> E[airplanes.live API] E --> F[Aircraft Data] F --> G[Formatted Response] G --> A

- 🐍 Python 3.8+
- 💻 Claude Desktop
- 🌐 Internet connection

# 1. Clone the repository git clone https://github.com/Bellaposa/airplanes-live-mcp.git cd airplanes-live-mcp # 2. Create virtual environment (REQUIRED!) python -m venv .venv # 3. Activate virtual environment # macOS/Linux: source .venv/bin/activate # Windows: .venv\Scripts\activate # 4. Install dependencies pip install -r requirements.txt # 5. Test the server python airplane_server.py

- If you skip step 2-3, you'll getModuleNotFoundError: No module named 'httpx'
- Claude Desktop needs thefull pathto the venv Python, not system Python
- Without venv, dependencies aren't isolated and things break

- Virtual env creates.venv\Scripts\folder (not.venv\bin\)
- UseScripts\python.exein Claude config, notbin/python
- Always use double backslashes\\in JSON paths

- Make sure Python 3.8+ is installed:python --version
- Ifpythondoesn't work, trypython3orpy
- Virtual environment MUST exist before configuring Claude Desktop

Skip Python setup headaches - use Docker instead!

- 🐳 Docker Desktop installed and running
- 💻 Claude Desktop

# 1. Clone the repository git clone https://github.com/Bellaposa/airplanes-live-mcp.git cd airplanes-live-mcp # 2. Build Docker image docker build -t airplane-mcp-server . # 3. Test the container docker run --rm -it airplane-mcp-server python airplane_server.py

⚙️ Claude Desktop Configuration for Docker

Add to~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "airplanes-live": { "command": "docker", "args": [ "run", "--rm", "-i", "airplane-mcp-server", "python", "airplane_server.py" ] } } }

Add to%APPDATA%\Claude\claude_desktop_config.json:

{ "mcpServers": { "airplanes-live": { "command": "docker", "args": [ "run", "--rm", "-i", "airplane-mcp-server", "python", "airplane_server.py" ] } } }

# Build the image docker build -t airplane-mcp-server . # Run interactively for testing docker run --rm -it airplane-mcp-server bash # Check if image exists docker images | grep airplane-mcp-server # Remove image if needed docker rmi airplane-mcp-server # View container logs (if running detached) docker logs <container_id>

- 🚀No Python setup required- Everything pre-configured
- 🔒Isolated environment- No dependency conflicts
- 🌍Works everywhere- Same setup on Windows/Mac/Linux
- 📦Easy updates- Just rebuild the image
- 🛡️Consistent behavior- Eliminates "works on my machine"

Problem: "docker: command not found"

# Install Docker Desktop first # macOS: https://docs.docker.com/desktop/install/mac-install/ # Windows: https://docs.docker.com/desktop/install/windows-install/ # Linux: https://docs.docker.com/desktop/install/linux-install/

Problem: "Cannot connect to Docker daemon"

# Start Docker Desktop application # Wait for Docker to fully start (green icon)

Problem: "Permission denied" (Linux)

# Add user to docker group sudo usermod -aG docker $USER # Log out and back in, or: newgrp docker

# Clean Docker cache docker system prune -a # Try building again docker build --no-cache -t airplane-mcp-server .

For the simplest setup, use Docker Compose:

# 1. Clone and enter directory git clone https://github.com/Bellaposa/airplanes-live-mcp.git cd airplanes-live-mcp # 2. Build and run with one command docker-compose up --build # 3. In another terminal, test the server docker-compose exec airplane-mcp-server python airplane_server.py

{ "mcpServers": { "airplanes-live": { "command": "docker-compose", "args": [ "-f", "/path/to/airplanes-live-mcp/docker-compose.yml", "exec", "-T", "airplane-mcp-server", "python", "airplane_server.py" ], "cwd": "/path/to/airplanes-live-mcp" } } }

{ "mcpServers": { "airplanes-live": { "command": "docker", "args": [ "run", "--rm", "-i", "airplane-mcp-server", "python", "airplane_server.py" ] } } }

{ "mcpServers": { "airplanes-live": { "command": "docker-compose", "args": [ "-f", "/full/path/to/your/airplanes-live-mcp/docker-compose.yml", "exec", "-T", "airplane-mcp-server", "python", "airplane_server.py" ], "cwd": "/full/path/to/your/airplanes-live-mcp" } } }

# 1. Clone and build git clone https://github.com/Bellaposa/airplanes-live-mcp.git cd airplanes-live-mcp docker build -t airplane-mcp-server . # 2. Configure Claude Desktop with Method 1 (above) # 3. Restart Claude Desktop completely # 4. Test with: "Show me aircraft near New York"

# Start services in background docker-compose up -d # View logs docker-compose logs airplane-mcp-server # Stop services docker-compose down # Rebuild and restart docker-compose up --build

### ⚙️ Claude Desktop Configuration #### 🍎 macOS/Linux Configuration Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/claude-desktop/config.json (Linux): 

Add to%APPDATA%\Claude\claude_desktop_config.json:

- UseScripts\\python.exe(notbin/python)

- ReplaceYourUsernamewith your actual Windows username

- Use double backslashes\\in paths

- Make sure the virtual environment is created withpython -m venv .venv

All tools useasyncto handle multiple requests efficiently:

This allows the server to handle concurrent requests without blocking.

All parameters are strings because MCP protocols work best with simple types:

Every tool includes comprehensive error handling:

Theformat_aircraft_data()function provides consistent, readable output:

Themake_api_request()function centralizes HTTP logic:

- Centralizes error handling

- Manages timeouts

- Logs all requests

- Makes it easy to add authentication later

aircraft_by_hex(hex_id: str = "")
Purpose: Search for aircraft by Mode S hex identifier
Input: Comma-separated hex IDs (e.g., "45211e,45212f")
Returns: List of matching aircraft with full details

aircraft_by_callsign(callsign: str = "")

Purpose: Search for aircraft by flight callsign
Input: Comma-separated callsigns (e.g., "BA387,AA123")
Returns: Aircraft matching the callsign

aircraft_by_registration(reg: str = "")

Purpose: Search for aircraft by tail number/registration
Input: Comma-separated registrations (e.g., "N123AB,G-EUPA")
Returns: Aircraft matching the registration

aircraft_by_type(icao_type: str = "")

Purpose: Search for aircraft by ICAO type code
Input: Type codes (A321, B738, C172, E190, etc.)
Returns: All aircraft of that type currently flying

aircraft_by_squawk(squawk_code: str = "")