About XHelio-SPICE
XHelio-SPICE is a spacecraft ephemeris tool for heliophysics researchers, wrapping SpiceyPy with automatic NAIF kernel downloads, caching, and loading. It provides position, trajectory, state, and coordinate-transform queries, including through MCP for LLM use.
Key features
- 01Automatic SPICE kernel download and caching
- 02Query spacecraft positions, trajectories, and states
- 03Transform coordinate frames and vectors
- 04List missions, aliases, and coordinate frames
- 05Manage kernel loading and cache
Use cases
- 01Find a spacecraft's position relative to the Sun
- 02Retrieve a spacecraft trajectory over a time range
- 03Transform vectors between coordinate frames
MCP support
Includes an MCP server that exposes ephemeris queries, distance calculations, coordinate transforms, mission and frame listings, and kernel management to LLM clients.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx xhelio-spiceXHELIO_SPICE_KERNEL_DIROverride the default kernel cache directory (~/.xhelio_spice/kernels/)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMExhelio-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
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 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 |
MCP smoke test
For a CI-safe MCP check that does not request kernel downloads, run:
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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.