astrodynamics-mcp¶

Model Context Protocol server giving any LLM client (Claude, ChatGPT, Cursor, custom agents) authoritative astrodynamics tools — TLE/SGP4, Lambert, ground-station access, time/frame conversions, porkchop, B-plane, satellite metadata, and — behind optional extras — NASA GMAT mission analysis, SPICE/NAIF queries, and trajectory visualisation.

What it is¶

LLMs reason well about astrodynamics concepts but cannot do the numerical work — they cannot propagate orbits, solve Lambert problems, or query SPICE ephemerides. astrodynamics-mcp lets you plug authoritative tools into any Model Context Protocol-capable client so the LLM calls vetted upstream libraries instead of hallucinating numbers.

The base surface wraps nine tools across the most common single-satellite questions: eight no-auth tools — tle_lookup, sgp4_propagate, lambert_solve, access_windows, time_convert, frame_transform, porkchop, bplane_target — plus satellite_metadata, which pulls persistent object metadata (mass, dimensions, launch, operator) from ESA DISCOSweb with a per-user credential. tle_lookup can also fall back to Space-Track for deeper, fresher catalogue records when you provide a credential — see Credentials.

Installing the [gmat] extra adds five GMAT mission-analysis tools, letting a client author, validate, run, and sweep NASA GMAT mission scripts and read back their reports and ephemerides.

Installing the [spice] extra adds the SPICE tools — backed by NASA NAIF's CSPICE via spiceypy — so a client can furnish kernels, query a body's state from an SPK, rotate vectors between kernel-defined frames (including non-Earth body-fixed ones), read body constants, and convert between the SPICE time systems.

Installing the [viz] extra adds four visualisation tools — backed by matplotlib and the gmat-czml sibling — so a client can render a ground track or trajectory as a PNG, draw a porkchop contour, or export a trajectory as a CZML document for a Cesium 3D globe. Each returns the picture as an attachment beside the numeric summary, so a text-only client still gets the answer.

Quick start¶

Install the server:

uv tool install astrodynamics-mcp     # or: pipx install astrodynamics-mcp

Add it to your MCP client. Claude Code, for example:

{
  "mcpServers": {
    "astrodynamics-mcp": {
      "command": "astrodynamics-mcp",
      "args": ["stdio"]
    }
  }
}

Restart the client. The base tools appear in its tool list. Ask:

Compute the Hohmann Δv from a 250 km circular LEO to GEO.

The LLM calls lambert_solve instead of guessing, and quotes a number you can reproduce.

Now plot Hubble passes above 10° from Madrid for the next seven days.

tle_lookup fetches the current Hubble TLE from CelesTrak; access_windows returns AOS/LOS/peak-elevation triples; the client formats them.

Next¶

Getting started — install paths and the full vision conversation.
Pick a client — Claude Code, Cursor, ChatGPT desktop, raw Python.
Tool reference — every tool with its current input / output schema.
Recipes — worked examples covering the canonical workflows.

What it is not¶

A general-purpose astrodynamics framework. astrodynamics-mcp wraps existing libraries; it does not re-implement propagators, integrators, or coordinate systems. For direct (non-MCP) Python access to the same surfaces, reach for the upstream libraries:

SGP4 / TLE propagation → sgp4
Lambert's problem → lamberthub
Ground-station / observer geometry → skyfield
Time scales and coordinate frames → astropy

See the FAQ for the full "what astrodynamics-mcp is not" list.

License¶

MIT — see LICENSE.