astrodynamics-mcp

A Model Context Protocol server that gives any MCP-capable LLM client (Claude Code, Cursor, ChatGPT desktop, custom agents) authoritative astrodynamics tools: TLE/SGP4 propagation, Lambert solving, ground-station access, time-scale and coordinate-frame conversions, porkchop scans, B-plane targeting, satellite metadata, and — with optional extras — full NASA GMAT mission execution ([gmat]), NASA SPICE / NAIF kernel queries ([spice]), and trajectory visualisation ([viz]).

Why

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 MCP-capable client so the LLM calls vetted upstream libraries instead of fabricating numbers. Every result carries explicit units; every tool description tunes against an Inspect AI eval suite that measures whether the LLM picks the right tool and binds the right arguments.

Tools

Tool	What it does	Backed by
`tle_lookup`	Fetch current TLEs by NORAD ID, name, or group — from CelesTrak (default) or Space-Track.	CelesTrak `gp.php` API · Space-Track †
`sgp4_propagate`	Propagate TLEs across UTC ISO 8601 epochs in TEME / ICRF / GCRS / ITRS / CIRS.	`sgp4`
`lambert_solve`	Solve Lambert's problem; multi-rev solutions enumerated; two-impulse Δv on demand.	`lamberthub`
`access_windows`	Ground-station / observer access intervals over a window, with AOS / LOS / peak elevation.	`skyfield`
`time_convert`	UTC / TAI / TT / TDB / UT1 / GPS / TCB / TCG conversions across ISO / JD / MJD / J2000-seconds / Unix.	`astropy.time`
`frame_transform`	State-vector transforms across ICRF / ITRS / GCRS / TEME / CIRS / TIRS / IAU body-fixed frames.	`astropy.coordinates`
`porkchop`	(depart × arrive) Δv / C3 grid for interplanetary transfers, ASCII contour, summary or full output.	`lamberthub` + JPL Horizons
`bplane_target`	B-plane element calculation and impulsive targeting for hyperbolic flybys.	in-house, JPL Horizons fed
`satellite_metadata`	Physical & provenance metadata (mass, dimensions, COSPAR ID, launch, operator, decay status) for a NORAD ID.	ESA DISCOSweb †

† Credentialed source. Pass credentials as environment variables for the stdio transport, or in the session-init _meta block for HTTP — see Credentials. A tool called without its credential returns a typed CredentialRequiredError, never a silent failure.

GMAT tools (optional `[gmat]` extra)

Install the [gmat] extra and have a local NASA GMAT install, and five more tools register for driving real GMAT missions (they stay hidden otherwise):

Tool	What it does	Backed by
`gmat_run_mission`	Run a complete GMAT mission; returns a parsed summary, report data, and pointers to large outputs.	`gmat-run`
`gmat_sweep`	Parameter sweeps and Monte Carlo (grid / samples / Monte Carlo / Latin hypercube) over a mission.	`gmat-sweep`
`gmat_execute_script`	Escape hatch — run raw GMAT script text and return its reports verbatim; engine errors come back as data.	`gmat-run`
`gmat_validate_script`	Parse-validate a script without running it; returns errors, warnings, and the resource/command structure.	`gmat-run`
`gmat_read_run_artefact`	Read the raw text of a file produced by a prior run (ephemerides, reports too large to inline).	run registry

SPICE tools (optional `[spice]` extra)

Install the [spice] extra and seven more tools register, backed by NASA NAIF's CSPICE through spiceypy (they stay hidden otherwise). They furnish kernels into a process-global pool and query whatever the pool holds:

Tool	What it does	Backed by
`spice_load_kernel`	Furnish a kernel into the pool from a local path or a NAIF `https` URL (allowlisted, cached); a meta-kernel furnishes all it lists.	`spiceypy` · NAIF
`spice_list_kernels`	List the kernels currently furnished in the pool, optionally filtered by category.	`spiceypy`
`spice_unload_kernel`	Drop a furnished kernel by the `name` `spice_load_kernel` returned.	`spiceypy`
`spice_state`	Position / velocity of a target relative to an observer at one or more epochs, from furnished SPK kernels.	`spiceypy` (SPK)
`spice_frame_transform`	Rotate a vector between kernel-defined frames — in particular non-Earth body-fixed frames — or return the rotation matrix.	`spiceypy` (FK / PCK)
`spice_body_parameters`	Read a body's radii, GM, and pole / prime-meridian orientation constants from furnished PCK kernels.	`spiceypy` (PCK)
`spice_time_convert`	Convert between the kernel-defined time systems ET / UTC / SCLK using furnished LSK / SCLK kernels.	`spiceypy` (LSK / SCLK)

The kernel model, the NAIF furnish-from-URL allowlist, and the process-global pool's trust boundary are covered on the SPICE integration page.

Visualisation tools (optional `[viz]` extra)

Install the [viz] extra and four more tools register, backed by matplotlib (static PNG plots) and the gmat-czml sibling (CZML export) — they stay hidden otherwise. Each returns its picture as an attachment alongside a numeric summary, so a text-only client still gets the answer:

Tool	What it does	Backed by
`plot_ground_track`	Render a satellite's sub-satellite ground track as a PNG over a lon/lat graticule, with the latitude / longitude extent inline.	`matplotlib`
`plot_trajectory`	Render an orbit or transfer arc as a 2D or 3D PNG about a central body, with arc length and apsides inline.	`matplotlib`
`plot_porkchop`	Render a porkchop C3 contour as a PNG from a full `porkchop` grid result — no recompute — with the best cell marked.	`matplotlib`
`czml_trajectory`	Export a trajectory as a CZML document for a Cesium 3D client, returned as an embedded resource.	`gmat-czml`

The attachment model — additive PNG ImageContent / CZML EmbeddedResource beside the structured summary — and which clients render each kind are covered on the Visualisation page.

Full input / output JSON schemas live on the Tool reference page of the docs site.

Quick start

Install:

bash

uv tool install astrodynamics-mcp            # or: pipx install astrodynamics-mcp
uv tool install "astrodynamics-mcp[gmat]"    # adds the GMAT mission tools (needs a local GMAT install)
uv tool install "astrodynamics-mcp[spice]"   # adds the SPICE tools (pulls spiceypy / bundled CSPICE)
uv tool install "astrodynamics-mcp[viz]"     # adds the visualisation tools (pulls matplotlib / gmat-czml)

Claude Code

Add to your Claude Code MCP settings:

config.json

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

Restart Claude Code. In a chat:

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

(The model calls lambert_solve with the Hohmann geometry and answers ≈ 3.91 km/s, citing the tool output — not the LLM's own weights.)

Cursor

~/.cursor/mcp.json (or workspace-level .cursor/mcp.json):

config.json

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

Restart Cursor. The tools appear under the astrodynamics server group.

See Pick a client in the docs for ChatGPT desktop, a raw Python MCP smoke client, and the Streamable HTTP transport for remote agents.

Supported clients

Client	Transport	Verified
Claude Code	stdio	✅ Yes
Cursor	stdio	✅ Yes
ChatGPT desktop	stdio	⏳ Expected to work
Raw Python (`mcp` SDK)	stdio	✅ Yes
Remote agents	Streamable HTTP	⏳ Expected to work
LangGraph / AutoGen / CrewAI	any	⏳ Expected to work

What this is not

Not a general-purpose astrodynamics framework. Wraps vetted upstream libraries; does not re-implement propagators, integrators, or coordinate systems.
Not an agent framework. Exposes MCP tools; LangGraph, AutoGen, CrewAI, and the LLM clients themselves consume them.
Not an ML / inference server. Tools that need their own ML models (maneuver detection, neural propagators) belong in separate MCP servers — kept modular for dependency isolation.
Not a SaaS. Runs locally or in your own infrastructure. No hosted multi-tenant deployment.
Not a web UI. Tool consumption is via MCP clients; no browser frontend, no desktop app, no notebook widget.

For direct (non-MCP) Python use of the same surfaces, reach for the upstream libraries: sgp4, lamberthub, skyfield, astropy, interplanetary-porkchop, spiceypy.

Built on

The official Anthropic modelcontextprotocol/python-sdk (MIT). The bundled FastMCP server class is the server primitive; stdio + Streamable HTTP transports are first-class.

Docs and links

Docs site: astro-tools.github.io/astrodynamics-mcp — getting started, per-client setup, tool reference, recipes, visualisation, data sources, eval suite, FAQ.
Issue tracker: astro-tools/astrodynamics-mcp/issues
Discussions: orgs/astro-tools/discussions — usage help and open-ended questions.
Eval suite: eval/README.md — the regression contract on tool-description quality.

Privacy

astrodynamics-mcp runs entirely on your own machine and collects nothing — no telemetry, no analytics, no accounts. The only data that leaves your machine is the query parameters a tool sends to the data source it wraps (CelesTrak / JPL Horizons / IERS with no auth, and — only if you configure their credentials — Space-Track and ESA DISCOSweb). Credentials are read from local environment variables or the session _meta block and are sent only to their own service over HTTPS. See the Privacy page for the full breakdown.

License

MIT — see LICENSE.