XHelio-SPICE

io.github.huangzesenPublished by GitHub account huangzesenv0.5.1Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyData & AnalyticsAI & ML

Overview

AI-generated overview

A local MCP server that gives an assistant spacecraft ephemeris tools, auto-downloading and caching NAIF SPICE kernels for heliophysics missions.

What you can do
Compute spacecraft position and velocity at a single time or as a CSV timeseries, and distances between two bodies, using SPICE kernels downloaded on demand and cached locally. Transform vectors between coordinate frames such as J2000, ECLIPJ2000, GSE and RTN. List supported missions and available coordinate frames with descriptions. Manage the kernel cache, including ensuring mission kernels are downloaded and loaded and freeing memory.
When to use it
Useful when working with heliophysics or planetary mission trajectories — Parker Solar Probe, Solar Orbiter, STEREO-A, Juno, Voyager, New Horizons and similar — and you want an assistant to answer position, distance or frame-conversion questions without handling SPICE setup by hand.
Requirements
Runs as a local Python process; install the package with the MCP extra and start the xhelio-spice-mcp command (or the module entry point). Network access is needed on first use to download kernels from NAIF, which are cached under ~/.xhelio_spice/kernels/ unless XHELIO_SPICE_KERNEL_DIR overrides it. No authentication is declared.
Before you install
The server downloads kernel files from NAIF over the network and writes them to a local cache directory, so disk use grows with the missions queried. Only some missions have auto-downloaded kernels; others are listed by NAIF ID only or need multi-segment loading that is not yet supported, so results may be unavailable for them.

Installation

In SourceWeft

  1. Open XHelio-SPICE in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
pip install xhelio-spice

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

bash
pip install xhelio-spice[mcp]

Quick Start

python
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 DataFramedf = 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

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

python
from xhelio_spice import get_position, get_trajectory, get_state
# Single positionpos = 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

python
from xhelio_spice import transform_vector, list_available_frames
# J2000 to Eclipticv_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 framesprint(list_available_frames())

Mission Registry

python
from xhelio_spice import resolve_mission, list_supported_missions
# Resolve name aliasesnaif_id, key = resolve_mission("Parker Solar Probe")  # -> (-96, "PSP")
# List all spacecraftmissions = list_supported_missions()

Kernel Management

python
from xhelio_spice import get_kernel_manager
km = get_kernel_manager()km.ensure_mission_kernels("PSP")  # Download + loadprint(km.get_cache_info())        # Cache statskm.unload_all()                    # Free memory

Configuration

MethodDescription
XHELIO_SPICE_KERNEL_DIR env varOverride 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:

bash
# Run directlyxhelio-spice-mcp
# Or via Pythonpython -m xhelio_spice.server

Claude Desktop Configuration

Add to claude_desktop_config.json:

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

Available MCP Tools

ToolDescription
get_ephemerisPosition/velocity — single time (inline) or timeseries (CSV)
compute_distanceDistance between two bodies
transform_coordinatesCoordinate frame transform
list_spice_missionsSupported missions
list_coordinate_framesAvailable frames with descriptions
manage_kernelsKernel cache management

MCP smoke test

For a CI-safe MCP check that does not request kernel downloads, run:

bash
uv run --extra mcp python scripts/smoke_mcp_list_tools.py --json

The smoke starts the stdio server with an isolated temporary kernel cache, runs MCP initialize + list_tools, and verifies the advertised tool names.

License

MIT

Source: README.md at commit 9aeb318

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts