heliofleet-mcp
A small Model Context Protocol server that answers spacecraft-geometry questions from HelioFleet's published data: where the heliophysics fleet is, what each spacecraft sees of the Sun, and when two of them line up. It is a thin layer over HelioFleet's static JSON files (JPL Horizons ephemerides, 2010 to about 2030, refreshed monthly). Nothing is recomputed from scratch. The frame and alignment code is a line-by-line port of the page's own JavaScript, so the numbers match the site.
Every answer carries a HelioFleet link that reproduces the view in the browser.
Tools
| Tool | What it returns |
|---|---|
get_position(body, time) |
Distance from the Sun; Stonyhurst lon/lat; Carrington longitude seen from Earth; ecliptic J2000 and HEE vectors; angle from Earth and distance to Earth; light time; Parker-spiral footpoint |
get_fleet_state(time) |
The same columns for Earth, every spacecraft on the map, and optionally Mercury, Venus and Mars |
find_alignments(kind, a, b, tolerance_deg, start, end) |
Windows of radial alignment, quadrature with Earth, solar conjunction (behind the Sun seen from Earth) or magnetic connection (Parker-spiral footpoints). Each window has start, end, best time and value, plus a link that reruns the search on the page |
list_upcoming_events(start, end) |
HelioFleet's calendar: perihelia, alignments, quadratures, conjunctions and eclipses. Optionally adds DONKI flares, CMEs and storms |
viewing_geometry(observer, time) |
Light time and offset from Earth, RSUN_OBS, B0, HGLN_OBS, L0 (CRLN_OBS, the observer's own light time), km per arcsec and scale relative to Earth, with a sky-view link |
heliofleet_link(...) |
A map or sky-view URL for a time, frame, zoom, hidden bodies, surface spot, tab or alignment search |
data_status() |
Which data release is loaded, where it came from, and each body's span |
HelioField plugin (on by default)
These tools add the coronal magnetic field from HelioField's daily PFSS products. They read published files and do not solve the field.
| Tool | What it returns |
|---|---|
magnetic_connection(body, date, solar_wind_km_s) |
Where Earth, the L1 fleet, Parker, Solar Orbiter, BepiColombo or STEREO-A connects to the Sun: the Parker-spiral point on the source surface, the PFSS footpoint (Carrington), the expansion factor, distance to the coronal-hole boundary and a WSA-type speed. self_consistent=True uses each body's own speed estimate |
space_weather(date) |
Model wind speed and sector at Earth, the next sector boundary, a −1 to +7 day outlook, an alert level, and that day's solar wind measured at L1 |
coronal_field(date) |
Magnetogram, PFSS settings, open flux and Earth's L0/B0, plus solar-cycle context per Carrington rotation (open flux and area, current-sheet tilt, polar fields; any date since 2010) |
heliofield_link(...) |
A link to the 3D corona, connectivity, space-weather or observations page |
Daily products cover about the last two months. For older dates the tools return links, because the
HelioField page computes any date since 2010-05-01 in the browser. HelioField's Carrington positions
of the fleet agree with HelioFleet's to 0.002°, and a test checks this. Set
HELIOFLEET_MCP_PLUGINS=none to serve the HelioFleet tools alone.
Bodies: earth sdo soho aditya ace wind dscovr imap swfo cgo solo psp bepi sta stb maven mercury venus mars.
Common names also work, such as "Parker", "Solar Orbiter" and "STEREO-A". Times are UTC in ISO 8601
(2026-11-19T12:00Z, 2026-11-19), now, or a Julian date.
Quick start
With uv installed, one command downloads and starts the server:
uvx heliofleet-mcp
It speaks MCP over stdio, so on its own it waits silently for a client. Register it with one:
Claude Code, for all projects:
claude mcp add heliofleet --scope user -- uvx heliofleet-mcp
Claude Desktop and other MCP clients take this mcpServers entry. In Claude Desktop it goes in
Settings → Developer → Edit Config, then restart the app. In a project, it can go in .mcp.json.
{
"mcpServers": {
"heliofleet": {
"command": "uvx",
"args": ["heliofleet-mcp"]
}
}
}
Then ask, for example, "When are Parker and Solar Orbiter next radially aligned?" To work offline
from a heliofleet checkout, add "env": {"HELIOFLEET_SOURCE": "local", "HELIOFLEET_LOCAL_DATA": "/path/to/heliofleet/data"} to the entry.
The server is also listed in the MCP Registry as
io.github.sr-dash/heliofleet-mcp.
Other ways to install
The only runtime dependency is the mcp Python SDK (1.x or 2.x); Python 3.10 or newer.
pipx install heliofleet-mcp # or: pip install heliofleet-mcp
heliofleet-mcp # or: python -m heliofleet_mcp
From a clone, for development:
git clone https://github.com/sr-dash/heliofleet-mcp && cd heliofleet-mcp
python3 -m venv .venv && .venv/bin/pip install -e '.[test]' jplephem
Example
When is the next Parker Solar Probe and Solar Orbiter radial alignment within 10° after 2026-11-19?
find_alignments(kind="radial", a="psp", b="solo", tolerance_deg=10, start="2026-11-19", max_windows=1):
{
"start_utc": "2026-12-01T16:00:00Z",
"end_utc": "2026-12-01T19:00:00Z",
"duration_days": 0.125,
"best_time_utc": "2026-12-01T18:00:00Z",
"best_value_deg": 6.173,
"a_at_best": {"body": "psp", "r_au": 0.0504, "hgs_lon_deg": 39.551, "hgs_lat_deg": -2.141},
"b_at_best": {"body": "solo", "r_au": 0.8614, "hgs_lon_deg": 37.749, "hgs_lat_deg": 3.763},
"link": "https://sr-dash.github.io/heliofleet/?t=2026-12-01T18:00Z&align=radial,psp,solo,10,2026-11-19,2027-11-19&tab=align#tools"
}
This is Parker's perihelion pass. Parker sweeps 4 to 5° an hour in Stonyhurst longitude and passes Solar Orbiter's longitude (37.7°). JPL Horizons gives separations of 8.91°, 6.29°, 6.18° and 9.07° at 16, 17, 18 and 19 UT.
Data and caching
Files are fetched from https://sr-dash.github.io/heliofleet/data/. They are cached under
~/.cache/heliofleet-mcp/<release>/, keyed by the manifest's build time, so a monthly update never
mixes with older files. The manifest is checked again every 6 hours. If the site cannot be reached,
the server uses the cached manifest, then a local heliofleet checkout. A sibling heliofleet/data
folder is found automatically.
| Variable | Default | Meaning |
|---|---|---|
HELIOFLEET_SOURCE |
auto |
auto (site, then local), web, or local |
HELIOFLEET_LOCAL_DATA |
sibling heliofleet/data |
local data folder |
HELIOFLEET_CACHE |
~/.cache/heliofleet-mcp |
cache folder |
HELIOFLEET_SITE |
https://sr-dash.github.io/heliofleet/ |
site root |
HELIOFLEET_MCP_PLUGINS |
heliofield |
optional tool sets, or none |
HELIOFIELD_SITE |
https://sr-dash.github.io/heliofield/ |
HelioField site root |
HELIOFIELD_LOCAL |
sibling heliofield |
local HelioField checkout |
HelioField files go in the same cache. Dated products are kept for good, and the index and series files are refreshed hourly.
Methods
- Positions are interpolated with HelioFleet's 4-point Lagrange scheme (
js/ephem.js). L1 monitors stored as geocentric km are added to Earth's heliocentric position (js/scene.js). - Stonyhurst (HEEQ) and Carrington coordinates use the IAU rotation model, as in SunPy (
js/frames.js). The pole is at RA 286.13°, Dec 63.87°, with W = 84.176° + 14.1844°/day since J2000 TT. Carrington longitudes see the Sun one light time in the past: Earth's light time for coordinate tables, the observer's own for viewing geometry (CRLN_OBS). - The alignment search (
js/tools.jsfindAlignments) samples hourly when Parker is involved and every 6 hours otherwise. Windows are runs of samples within the tolerance, so window edges sit on that grid. Solar conjunctions followscripts/build_calendar.py. - Spacecraft status follows the map:
ok,lost(a prediction after loss of contact), orapprox(SDO past the end of its ephemeris, shown at Earth).
Full methods: https://sr-dash.github.io/heliofleet/methods.html.
Tests
.venv/bin/pip install -e '.[test]' jplephem
.venv/bin/python -m pytest
test_reference.py: interpolation against JPL Horizons, and Stonyhurst/Carrington against SunPy, using HelioFleet's reference set (tests/data/reference.json). The limit is 0.005°. The worst case is 0.0004°.test_sunpy.py: frame conversions against SunPy computed live. It covers Earth's B0 and L0 againstsunpy.coordinates.sun, and Venus and Mars end to end against DE432s.test_alignments.py: windows identical to the page's ownfindAlignments(run live through Node when a heliofleet checkout is next to this one, otherwise a stored fixture), and the demo query against Horizons.test_server_stdio.py: the server started over stdio and called through the MCP client.test_data_sources.py: site fetch and cache (markednetwork), and the local fallback.test_heliofield.py: the plugin's daily products, links as in HelioField'sllms.txt, and HelioField's fleet positions and L0/B0 against HelioFleet's frames.
HELIOFLEET_TEST_SOURCE=web runs the suite on the live sites instead of local checkouts.
Releasing
- Set the new version in
src/heliofleet_mcp/__init__.pyand in bothversionfields ofserver.json, and add a section toCHANGELOG.md.python scripts/check_release.pychecks that they agree. - Commit, push, and publish a GitHub release tagged
vX.Y.Z. - The
releaseworkflow then runs the tests and builds the package. It publishes to PyPI by trusted publishing, attaches the files to the release, waits for PyPI, and publishesserver.jsonto the MCP Registry underio.github.sr-dash/heliofleet-mcp.
The tests workflow validates the package and server.json on every push.
Licence and citation
MIT. When you use positions from this server, please cite HelioFleet: Dash, S. (2026). HelioFleet: an interactive map of heliophysics spacecraft positions [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.23328187. Ephemerides: JPL Horizons. For coronal-field results, cite HelioField (https://doi.org/10.5281/zenodo.23487231) and the magnetogram (NSO/GONG or SDO/HMI).
Metadata
Release files for heliofleet-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| heliofleet_mcp-0.1.0.tar.gz | 45.5 kB | With provenance | Details for heliofleet_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| heliofleet_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for heliofleet_mcp-0.1.0-py3-none-any.whl |
Total release size: 75.9 kB
Release files / heliofleet_mcp-0.1.0.tar.gz
| Download URL | heliofleet_mcp-0.1.0.tar.gz |
|---|---|
| Size | 45.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9c7d9f8d8c5001c44f0e9ef617d6b5e4a896ebbdd5dab2b00548e126aaba0544
|
|
BLAKE2b-256 checksum How to use checksums |
93ae07c7e91481d84058a9416d2edb5056eb3b00a7dc0fea6910001559cdb298
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / heliofleet_mcp-0.1.0-py3-none-any.whl
| Download URL | heliofleet_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 30.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5c9652c30c11cf90f1795b8700cc39c895a30d276832d02eef183ec011ca38a3
|
|
BLAKE2b-256 checksum How to use checksums |
99b84ee86d6c53c3808f85358d4ff462f698fbc5306b5aa59f4fd696e2c72025
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for heliofleet-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for heliofleet_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.