aircraft_by_hexLABSCO SUMMARY
One public feed, no credentials, read-only.
A single-source tracker with a narrow job, done in one exchange: point at a place or a tail number and get back what is there right now, in readable lines. The thing to check before you build on it is the airplanes.live terms rather than the MIT licence on the code — the data is what carries the non-commercial restriction.
What it is
A small Python server over the airplanes.live feed, answering where aircraft are right now. Results come back formatted for reading — callsign, registration, type, position, altitude, ground speed, track, Mode S hex and how long ago the aircraft was seen — rather than as raw JSON, so an assistant can quote them straight back.
What you get
- Aircraft by Mode S hex identifier, flight callsign or tail registration, each accepting a comma-separated list
- Every aircraft of an ICAO type code currently flying
- Everything within a radius of a latitude and longitude
- Aircraft squawking a given transponder code, including the emergency, radio-failure and interference codes
- The military aircraft the feed tags as such
- The law-enforcement and special-interest categories the feed maintains
Requirements
No account and no key — the data is public. What governs use is the data licence rather than the code licence: airplanes.live provides the API for educational and non-commercial purposes, and this project is not affiliated with them, so it belongs in personal and classroom work rather than behind a product. The documented client configuration runs the server as a Docker container built from the repository. The plain Python path works too, but the virtual environment is not optional and the client must be given the full path to that environment's interpreter, not the system one. Radius searches and result sizes are capped by the upstream API, and a request times out rather than hanging.
Setup effort
Build from source — git clone https://github.com/Bellaposa/airplanes-live-mcp.git
USE CASES
01
Answering what that aircraft overhead is
Give it your latitude and longitude with a radius and get every aircraft in that circle, then look one of them up by its Mode S hex for the full record.
02
Following one flight or one airframe
Search by callsign for a specific flight, or by tail registration to follow a particular aircraft wherever it is flying. Both accept comma-separated lists.
03
Seeing everything of one type in the air
An ICAO type code returns every aircraft of that model currently flying, and the military list does the same for the airframes the feed tags as military.
04
Spotting aircraft flying a special code
Query a four-digit squawk to find aircraft signalling emergency, radio failure or interference, and check the law-enforcement and special-interest lists the feed maintains.
9 tools
Listed in project docs. Your client may show a different list.
aircraft_by_callsignaircraft_by_registrationaircraft_by_typeaircraft_by_squawkaircraft_near_positionmilitary_aircraftladd_aircraftpia_aircraftBEFORE YOU INSTALL
What to know first
Tools you get
9 tools named in the project's documentation.
Requires
docker on PATH
INSTALLATION
Connect your client
Server setup
TERMINAL
# 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.pyMCP Clients
Claude Desktop — Docker
CLAUDE DESKTOP — DOCKER · TERMINAL
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp
docker build -t airplane-mcp-server .CLAUDE DESKTOP — DOCKER · JSON
{
"mcpServers": {
"airplanes-live": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"airplane-mcp-server",
"python",
"airplane_server.py"
]
}
}
}Claude Desktop — macOS / Linux
CLAUDE DESKTOP — MACOS / LINUX · JSON
{
"mcpServers": {
"airplanes-live": {
"command": "<YOUR_PATH_TO_AIRPLANES_LIVE_MCP>/.venv/bin/python",
"args": [
"<YOUR_PATH_TO_AIRPLANES_LIVE_MCP>/airplane_server.py"
],
"env": {
"PYTHONPATH": "<YOUR_PATH_TO_AIRPLANES_LIVE_MCP>"
}
}
}
}Claude Desktop — Windows
CLAUDE DESKTOP — WINDOWS · JSON
{
"mcpServers": {
"airplanes-live": {
"command": "C:\\Users\\<YOUR_USERNAME>\\airplanes-live-mcp\\.venv\\Scripts\\python.exe",
"args": [
"C:\\Users\\<YOUR_USERNAME>\\airplanes-live-mcp\\airplane_server.py"
],
"env": {
"PYTHONPATH": "C:\\Users\\<YOUR_USERNAME>\\airplanes-live-mcp"
}
}
}
}Claude Desktop — Docker Compose
CLAUDE DESKTOP — DOCKER COMPOSE · TERMINAL
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp
docker-compose up --buildCLAUDE DESKTOP — DOCKER COMPOSE · JSON
{
"mcpServers": {
"airplanes-live": {
"command": "docker-compose",
"args": [
"-f",
"<YOUR_PATH_TO_AIRPLANES_LIVE_MCP>/docker-compose.yml",
"exec",
"-T",
"airplane-mcp-server",
"python",
"airplane_server.py"
],
"cwd": "<YOUR_PATH_TO_AIRPLANES_LIVE_MCP>"
}
}
}Leave the compose stack running — this configuration runs the server inside the airplane-mcp-server service with docker-compose exec. <YOUR_PATH_TO_AIRPLANES_LIVE_MCP> is the folder you cloned.
