xhelio-spice 0.6.1

Spacecraft ephemeris made easy — auto-managed SPICE kernels for heliophysics missions

xhelio-spice

Spacecraft ephemeris made easy — auto-managed SPICE kernels for heliophysics missions.

xhelio-spice wraps SpiceyPy with automatic kernel download, caching, and loading. Ask for a spacecraft position and xhelio-spice handles the rest: downloading the right NAIF kernels, loading them in the correct order, and returning results as Python dicts or pandas DataFrames.

Installation

pip install xhelio-spice

For MCP server support (Claude Desktop, Claude Code, Cursor, etc.):

pip install xhelio-spice[mcp]

Quick Start

from xhelio_spice import get_position, get_trajectory

# Where is Parker Solar Probe right now?
pos = get_position("PSP", observer="SUN", time="2024-01-15", frame="ECLIPJ2000")
print(f"PSP is {pos['r_au']:.3f} AU from the Sun")

# Get a month of trajectory data as a DataFrame
df = get_trajectory(
    "PSP", observer="SUN",
    time_start="2024-01-01", time_end="2024-01-31",
    step="1h", frame="ECLIPJ2000",
)
print(df[["r_au"]].describe())

Kernels are automatically downloaded from NAIF on first use and cached in ~/.xhelio_spice/kernels/.

Supported Missions

87 spacecraft with automatic kernel download, plus all major natural bodies.

Heliophysics

PSP, Solar Orbiter, STEREO-A/B, SOHO, IBEX, RBSP-A/B (Van Allen Probes), Helios 1/2, Ulysses, THEMIS A–E (incl. ARTEMIS), Pioneer 6/8

Planetary & Deep-Space

Cassini†, Juno, Galileo, Voyager 1/2, New Horizons, Dawn, MAVEN, MRO†, Mars 2020†, Mars Odyssey†, MGS†, MEX, MSL (Curiosity), InSight, Phoenix, MER Spirit/Opportunity, Viking 1/2, LRO†, Lunar Prospector†, Chandrayaan-1†, GRAIL A/B†, Clementine, LADEE, Lunar Orbiter 1–5, NEAR, Rosetta, MESSENGER, Magellan†, ExoMars TGO†, Pioneer 10/11, Pioneer Venus, VEX, OSIRIS-REx, Hayabusa, Deep Impact, EPOXI, Stardust†, Akatsuki†, Genesis, Giotto, SMART-1, Mariner 9/10, Vega 1, CONTOUR, IUE, Deep Space 1

Active & Upcoming

Europa Clipper, Lucy, Psyche, JUICE, BepiColombo, Hera

Observatories

JWST, HST, Chandra, Spitzer, Gaia, Euclid, INTEGRAL

Natural Bodies

Sun, Earth, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto

†Segmented missions — only kernel segments overlapping the requested time window are downloaded.

API Reference

Position & Trajectory

from xhelio_spice import get_position, get_trajectory, get_state

# Single position
pos = get_position("ACE", observer="EARTH", time="2024-06-01", frame="GSE")

# Full state (position + velocity)
state = get_state("PSP", observer="SUN", time="2024-01-15", frame="ECLIPJ2000")

# Trajectory timeseries (returns pandas DataFrame)
df = get_trajectory(
    "Cassini", observer="SATURN",
    time_start="2010-01-01", time_end="2010-12-31",
    step="6h", frame="ECLIPJ2000",
    include_velocity=True,
)

Coordinate Transforms

from xhelio_spice import transform_vector, list_available_frames

# J2000 to Ecliptic
v_ecl = transform_vector([1.0, 0.0, 0.0], "2024-01-15", "J2000", "ECLIPJ2000")

# RTN transform (requires spacecraft)
v_rtn = transform_vector(
    [5.0, -3.0, 1.0], "2024-01-15",
    from_frame="ECLIPJ2000", to_frame="RTN",
    spacecraft="PSP",
)

# List all frames
print(list_available_frames())

Mission Registry

from xhelio_spice import resolve_mission, list_supported_missions

# Resolve name aliases
naif_id, key = resolve_mission("Parker Solar Probe")  # -> (-96, "PSP")

# List all spacecraft
missions = list_supported_missions()

Kernel Management

from xhelio_spice import get_kernel_manager

km = get_kernel_manager()
km.ensure_mission_kernels("PSP")  # Download + load
print(km.get_cache_info())        # Cache stats
km.unload_all()                    # Free memory

Configuration

Method	Description
XHELIO_SPICE_KERNEL_DIR env var	Override kernel cache directory
KernelManager(kernel_dir=...)	Per-instance override
Default	~/.xhelio_spice/kernels/

MCP Server

xhelio-spice includes an MCP server for LLM tool use:

# Run directly
xhelio-spice-mcp

# Or via Python
python -m xhelio_spice.server

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "xhelio-spice": {
      "command": "xhelio-spice-mcp"
    }
  }
}

Available MCP Tools

Tool	Description
get_ephemeris	Position/velocity — single time (inline) or timeseries (CSV)
compute_distance	Distance between two bodies
transform_coordinates	Coordinate frame transform
list_spice_missions	Supported missions
list_coordinate_frames	Available frames with descriptions
manage_kernels	Kernel cache management

License

MIT