heliospice

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

heliospice wraps SpiceyPy with automatic kernel download, caching, and loading. Ask for a spacecraft position and heliospice 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 heliospice

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

pip install heliospice[mcp]

Quick Start

from heliospice 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 ~/.heliospice/kernels/.

Supported Missions

With SPICE Kernels (auto-downloaded)

• PSP (Parker Solar Probe) — 2018-2030
• Solar Orbiter (SOLO) — 2020-2030
• STEREO-A — 2017-2031
• Juno — 2011-present (updated regularly)
• Voyager 1/2 — 1981-2100 / 1989-2100
• New Horizons — 2019-2030

NAIF IDs Only (no auto-download yet)

• ACE, Wind, DSCOVR, MMS (1-4) — no public SPK kernels exist
• Cassini, MAVEN — require multi-segment kernel loading (planned)
• Galileo, Pioneer 10/11, Ulysses, MESSENGER, STEREO-B

Natural Bodies

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

API Reference

Position & Trajectory

from heliospice 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 heliospice 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 heliospice 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 heliospice 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

MCP Server

heliospice includes an MCP server for LLM tool use:

# Run directly
heliospice-mcp

# Or via Python
python -m heliospice.server

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "heliospice": {
      "command": "heliospice-mcp"
    }
  }
}

Available MCP Tools

License

MIT