Skip to main content
Glama
danmarce

adsb-mcp

by danmarce
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

adsb-mcp

Live local ADS-B flight data as MCP tools, over your own receiver's aircraft.json (readsb / tar1090 / dump1090) — keyless, live, your own data. Answers "what's flying overhead right now?"

Tools

Tool

What it does

aircraft_overhead

Aircraft in range of the receiver, nearest first (needs ADSB_SITE_LAT/LON for distances; degrades gracefully without).

aircraft_near

Aircraft within a radius of a point you pass (no receiver location needed).

find_aircraft

Match by callsign / ICAO hex / registration (partial, case-insensitive).

Data is structured (hex, callsign, registration, type, altitude_ft, ground_speed_kt, track_deg, lat/lon, distance_km + bearing_deg when the site is set, seen_s). Every result has a status: ok / refused (caller-fixable, with advice) / error (receiver unreachable). ADS-B carries no route/airline — that's a separate optional enrichment tier (not these tools).

Related MCP server: Aviation MCP Server

Run

uv sync                      # (--system-certs behind a TLS-inspecting proxy)
# stdio:
uv run adsb-mcp serve
# streamable-http (behind mcpo / on the LAN):
ADSB_MCP_TOKEN=... ADSB_URL=http://<feeder-host>:8080/data/aircraft.json \
  ADSB_SITE_LAT=... ADSB_SITE_LON=... \
  uv run adsb-mcp serve --transport http --host 0.0.0.0 --port 8000

Config (env)

Var

Default

Notes

ADSB_URL

http://localhost:8080/data/aircraft.json

Your feeder's live snapshot (readsb / tar1090 path).

ADSB_SITE_LAT / ADSB_SITE_LON

—

Receiver location for nearest-first overhead. Home-location PII — from 1Password, never committed. Unset = overhead without distances.

ADSB_MCP_TOKEN

—

Bearer required on streamable-http when set.

ADSB_HTTP_TIMEOUT

10

Seconds.

Claude Desktop / Claude Code (stdio)

{
  "mcpServers": {
    "adsb": {
      "command": "uv",
      "args": ["--directory", "/path/to/adsb-mcp", "run", "adsb-mcp", "serve"],
      "env": { "ADSB_URL": "http://<feeder-host>:8080/data/aircraft.json" }
    }
  }
}

Docker

docker build -t adsb-mcp .
docker run --rm -p 8000:8000 -e ADSB_MCP_TOKEN=... \
  -e ADSB_URL=http://<feeder-host>:8080/data/aircraft.json \
  -e ADSB_SITE_LAT=... -e ADSB_SITE_LON=... adsb-mcp

The server is stateless: no database, no volume. It needs to reach your feeder over the LAN. Inside the container localhost is the container itself, so set ADSB_URL to the feeder's address.

Auth and exposure

Auth is deliberately simple: stdio, or streamable-HTTP with a single bearer token (ADSB_MCP_TOKEN) on a private network, for example behind mcpo. /healthz stays open. There is no OAuth, no users and no audit log, by design. To publish it more widely, put a management layer in front of it: an MCP gateway or auth proxy that handles OAuth, users and audit for all your servers at once. Keep in mind that ADSB_SITE_LAT/LON is your home location, and aircraft_overhead echoes it back as observer: anyone who can call the tool can read it.

AI assistance

adsb-mcp is developed openly with the help of Claude (Anthropic). Commits Claude helped write carry a Co-Authored-By: Claude trailer. The code and design are open source so the work can be inspected, reused, and given back.

License

MPL-2.0 © Daniel Núñez.

Available Tools

3 tools
aircraft_nearAircraft near a pointA
Read-onlyIdempotent

Aircraft currently within radius_km of a given point (lat/lon you supply — e.g. a city), nearest first. Unlike aircraft_overhead this needs no receiver location: distance is measured from the point you pass.

    Args:
        latitude/longitude: the centre point to search around.
        radius_km: search radius in kilometres (default 50).
        max_results: cap on aircraft returned (default 10).
        include_grounded: include aircraft on the ground (default False).
ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYes
longitudeYes
radius_kmNo
max_resultsNo
include_groundedNo

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real behavioral context: results are ordered nearest-first and no receiver location is required. It does not disclose rate limits, empty-result behavior, or freshness of the live data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and sibling contrast are front-loaded in the first two sentences; the Args block is compact. It does restate defaults already present in the schema, which is mild redundancy but aids scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description never says what is returned per aircraft or how an empty result is signalled, only the cap and ordering. For a read-only lookup tool the essentials for invocation are present, but the return contract is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the burden and does compensate: all five parameters are explained, including units (kilometres) and defaults (50, 10, False) plus the meaning of include_grounded. It stops short of acceptable lat/lon ranges or format constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+scope: 'Aircraft currently within radius_km of a given point', with explicit ordering ('nearest first'). It also names the sibling it differs from (aircraft_overhead), so an agent can distinguish the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly explains when this tool applies versus aircraft_overhead: it needs no receiver location because distance is measured from the supplied point. The find_aircraft sibling is never addressed, and there is no when-not-to-use guidance, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aircraft_overheadAircraft overheadA
Read-onlyIdempotent

Aircraft currently in range of the receiver, nearest first. The "what's that plane overhead right now" query. With the receiver location configured, each result carries distance_km + bearing; without it, results are listed newest-position-first and distance is null (set ADSB_SITE_LAT/LON).

    Args:
        max_results: cap on aircraft returned (default 10).
        include_grounded: include aircraft on the ground (default False — only airborne).
ParametersJSON Schema
NameRequiredDescriptionDefault
max_resultsNo
include_groundedNo

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover read-only/idempotent/openWorld=false, and the description adds real behavioral context beyond them: the config-dependent sort order, distance_km being null without a site location, and the env vars to set. It doesn't cover rate limits or result freshness, but the config-conditional behavior is substantive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what it returns, then the config conditional, then args. Mostly tight, though the quoted colloquialism and parenthetical env var hint are slightly casual for a tool spec.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-param read-only tool with no output schema, the description covers the return ordering, distance/bearing semantics, config dependency, and both params. It doesn't document the shape of each aircraft record (fields besides distance/bearing), but nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry parameter meaning. It documents both params with defaults and clarifies semantics (max_results is a cap, include_grounded defaults to airborne-only), though it doesn't document valid ranges for max_results.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+scope: aircraft currently in range, nearest first. The phrase 'what's that plane overhead right now' quote concretely distinguishes it from siblings like aircraft_near and find_aircraft, which suggest different query modes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage via the colloquial framing and mentions behavior with/without receiver config, but doesn't explicitly say when to use this vs aircraft_near or find_aircraft. The routing is inferable from the name and 'right now' framing but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_aircraftFind aircraftA
Read-onlyIdempotent

Find aircraft currently in range by a partial match on callsign, ICAO hex, or registration (case-insensitive). Returns matches even if they have no position yet.

    Args:
        query: text to match against callsign / hex / registration (e.g. "LAN", "e80", "CC-B").
        max_results: cap on matches returned (default 10).
ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
max_resultsNo

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond them: case-insensitive matching and the fact that matches are returned even when they have no position yet, which matters for result interpretation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core operation in the first sentence, then documents each argument compactly. The Args block is conventional and each line earns its place; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read tool with full annotation coverage and no output schema, the definition is essentially complete: matching rules, scope limitation ('currently in range'), and a result caveat are all present. Only inter-sibling disambiguation is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the parameter burden and largely does: query is defined as a case-insensitive partial match across three identifier fields with concrete examples ("LAN", "e80", "CC-B"), and max_results is described as a cap defaulting to 10. This compensates well for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Find) and resource (aircraft), plus the matching semantics: partial match across callsign, ICAO hex, or registration, case-insensitive. It does not explicitly differentiate itself from siblings aircraft_overhead and aircraft_near, so sibling routing is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'currently in range' implies a live-coverage context, but the description never states when to use this over aircraft_overhead or aircraft_near, nor any exclusions. Usage is implied rather than guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedaircraft_near
    • First observedaircraft_overhead
    • First observedfind_aircraft
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 3 tools

Disambiguation4/5

aircraft_overhead and aircraft_near are both 'aircraft in range, nearest first' spatial queries, but the descriptions clearly distinguish them (implicit receiver location vs. an explicit lat/lon you supply). find_aircraft is a clearly separate identifier-lookup path, so an agent can pick correctly.

Naming Consistency3/5

Two tools follow an aircraft_<modifier> pattern while the third is a verb_noun form (find_aircraft), and none use a consistent verb prefix. It is still readable and unprefixed-domain-consistent, but the convention is mixed.

Tool Count3/5

Three tools is on the thin side even for a narrow, read-only ADS-B query domain. It is defensible since each tool covers a distinct query mode, but the surface feels minimal.

Completeness3/5

Core live queries (overhead, radius, identifier lookup) are covered, but there is no tool for detailed single-aircraft data, historical/track positions, or receiver/feeder status. Agents can work around these gaps but cannot fully answer common questions like a plane's route or recent track.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers