io.github.cyanheads/astronomy-mcp-server

Search forward from a start time for the next occurrences of one sky-event class, selected by the `event` enum: solar_eclipse, lunar_eclipse, equinox, solstice, moon_quarter, opposition, conjunction, max_elongation, or perigee_apogee. Both eclipse classes take an optional observer (latitude and longitude together). solar_eclipse without one returns global eclipses — kind, peak time, obscuration, and for a total or annular eclipse the latitude/longitude where it is greatest; with one it returns only eclipses visible from that point, with local contact times, `local_visible`, and the Sun's altitude at each contact. lunar_eclipse returns geocentric contact times, the same instants everywhere on Earth; an observer adds `local_visible` and the Moon's altitude at each contact. Every other class is geocentric and ignores a location. The body-relative events (opposition, conjunction, max_elongation, perigee_apogee) require a `body`: opposition applies to the superior planets (mars through pluto), conjunction to any planet, max_elongation to mercury and venus, and perigee_apogee to the moon (perigee/apogee), earth, or a planet (perihelion/aphelion). conjunction with `body` alone is that planet's conjunction with the Sun. Add `body2` for a conjunction of two bodies — the Moon or a planet with another: the instant they share one ecliptic longitude seen from Earth's center, with their `separation_degrees` at that instant. That separation is not always their closest approach, since two planets can pass closer days or weeks away, and listings that time conjunctions by right ascension differ by hours, or by days for slow pairs. Returns the next `count` occurrences (default 1), up to 20 per call: a larger `count`, up to 200, returns the first 20 and a notice naming the exact `start` and `count` that continue the series. Searches stop at the end of 2100, the close of the supported span; when that leaves fewer than `count`, a notice says so. Start defaults to now; pass an IANA `timezone` for observer-local timestamps.

Fetch a time-series ephemeris for a small body (asteroid or comet) or spacecraft from JPL Horizons — RA/Dec, distance, and apparent magnitude over a span, optionally with observer-relative altitude/azimuth. This covers objects the in-process major-body set cannot. The designation is passed to Horizons verbatim, so it must be in a form Horizons resolves to a single record: a numbered asteroid takes a trailing-semicolon record lookup (e.g. "433;" for Eros, "1;" for Ceres), and a periodic comet takes the DES + closest-apparition form (e.g. "DES=1P;CAP" for Halley). Spacecraft take their negative SPK-ID. Anything else goes through the Horizons name search: a bare name matching nothing (e.g. "433 Eros") or several records (e.g. "1P/Halley") is rejected, but one matching a single object succeeds even when that object is not the one meant — "Eros" resolves to Kerberos, a moon of Pluto — so compare `target_name`, the object Horizons resolved, with the one intended. A major-body name matching several bodies (e.g. "Mars") is rejected with the ID number of each body it matched — pass one, such as "499" for the planet. `start` and `stop` are ISO 8601 UTC dates in the Gregorian calendar, extended before 1582, in years 0100 through 9999; `stop` must not be before `start`, and a `stop` equal to `start` returns the single row at that instant. `step` is a count plus a unit of m, h, d, mo, or y, such as "1d", "1h", or "10m". Supplying observer latitude/longitude yields topocentric coordinates and adds alt/az — supply both or neither. This is a gated, network-backed extension (JPL Horizons is keyless but rate-limited and best-effort); large spans truncate inline at 200 rows, and the truncation notice names the exact `start` to resume from — one step past the last row returned, because Horizons includes the start instant in its output — so re-calling from there continues the series without repeating a sample. Splitting the range into smaller adjacent spans works too; keep the same step either way so no sample is lost.

Report the Moon phase for an instant: illuminated fraction, phase name, synodic age in days since the new moon, phase longitude (the Moon–Sun ecliptic-longitude difference, 180° at full), and the next four quarter phases (new, first quarter, full, last quarter) with timestamps. Answers "what is the moon phase tonight" and "when is the next full moon" in one call without iteration. The time defaults to now; pass an IANA `timezone` to also receive observer-local timestamps. The phase is geocentric — no observer location is needed.

Compute rise, set, and culmination (transit) times for a body at an observer location, plus the maximum altitude at culmination. For the Sun, also returns the three twilight pairs (civil −6°, nautical −12°, astronomical −18°) so a single call answers "when does the sun set and when is it truly dark." Each pair covers the night after the cycle's set (after its culmination when it has none) — dusk that evening, dawn the next morning — so the dawn listed beside a sunrise is the following day's. A depth a night never reaches (astronomical twilight around midsummer at mid-to-high latitudes) is null for that night. When `start` falls between sunset and sunrise, the first cycle opens at the next sunrise and `night_in_progress` carries the night already under way, dusk through dawn, including times before `start` that have passed; otherwise, for the dawn before a sunrise, read the previous cycle or start a day earlier. Searches forward from `start` (default today) and returns the next `count` cycles (default 1), up to 31 per call: a larger `count`, up to 366, returns the first 31 and a notice naming the exact `start` and `count` that continue the series, or saying no call can when the next cycle starts after 2100; a continuation started just past a sunset repeats in `night_in_progress` the night the last cycle of the previous call carried, while its cycles pick up without overlap. When the body is already above the horizon at `start`, the first cycle is the interval in progress: its `set` is the imminent one and its `rise` is null, since that rise precedes the search — so a set is never reported earlier than the rise beside it. Circumpolar or never-rises situations are reported as null rise/set fields with an explanatory note rather than an error — the fact is the answer. One cycle covers one day: a day the body neither rises nor sets on (polar night, midnight sun) is a cycle of its own, so consecutive cycles are consecutive days and each night appears in exactly one cycle. When `start` falls after the culmination of such a polar-night day, or after the last sunset before one, the first cycle is the rest of that day — rise, set, and transit null — carrying the twilight of that night, including times before `start` that have passed. Default elevation is 0 m; pass an IANA `timezone` for observer-local times. This server does not geocode — resolve coordinates upstream first.

Predict visible passes of a satellite (e.g. the ISS, NORAD 25544) over an observer in the next `days`. Identify the satellite by exactly one of `norad_id` or `name` — supplying both, or neither, is rejected. A few well-known common names resolve directly to their catalog numbers, ignoring case: ISS or International Space Station (25544), Hubble, Hubble Space Telescope, or HST (20580), and Tiangong, CSS, or Chinese Space Station (48274). Any other `name` is matched as a case-insensitive substring of CelesTrak's catalog names, so it resolves only when it picks out a single object: a broader query comes back with the matching objects and their catalog numbers to choose from. Either way the result echoes the query that resolved it as `resolved_from_name`. Fetches the object's current GP element set from CelesTrak, propagates it with SGP4 in-process, and returns each pass's rise, peak, and set times with azimuths and the peak elevation, plus the stretch of the pass visible to the naked eye: `visible_start_utc` through `visible_end_utc`, with the elevation and azimuth at each end. A pass is returned when that visible stretch — the satellite above the horizon and sunlit while the Sun is below −6° for the observer — reaches 10° elevation, wherever in the pass it falls. `sunlit` reports illumination at the peak instant, so it is false on a pass seen only before it enters Earth's shadow or after it leaves. Rise, set, and the visible-stretch edges are within 1 s of the true instants; the peak is the highest sample of a 30-second scan. Every returned pass rises in the requested window or in the 30 s before `start`: a pass up longer than that at `start` is omitted rather than reported with `start` as its rise, so back up `start` to see it, while a pass still up when the window ends is reported through its actual set. Searches at most 10 days per call: a larger `days`, up to 30, searches the first 10 and returns a notice naming the exact `start` and `days` that continue the search with no pass repeated or skipped, while that start stays within about a month of the element set's epoch. A `start` further than about a month from the element set's epoch is rejected as out of range on that distance alone, and an element set that will not propagate to a window inside that horizon is rejected as a reentry — so an empty `passes` means only that nothing was visible. CelesTrak publishes only current element sets, so in practice `start` must be within about a month of today. NORAD catalog numbers and catalog names are found at celestrak.org or heavens-above.com. This is a gated, network-backed extension (CelesTrak is keyless but rate-limited; element sets are cached briefly). Default elevation 0 m; pass an IANA timezone for observer-local pass times.

Compute the apparent topocentric position of one solar-system body (sun, moon, mercury through neptune, pluto) or a named bright star for an observer location and instant. Returns equatorial (RA/Dec), refraction-corrected horizontal (altitude/azimuth), and ecliptic coordinates, plus distance, apparent magnitude, angular diameter, phase angle, illuminated fraction, angular distance from the Sun, and the constellation it falls in. For a solar-system body it also returns that body card — classification, mean radius, naked-eye visibility — the same values served at astronomy://body/{body}, so a client without resource support does not need a second surface to reach them; a catalog star has no card and the field is absent. Positions are parallax- and aberration-corrected for the given observer; default elevation is 0 m and the default time is now. Supply `star` (e.g. "Sirius", "Polaris") instead of `body` to target a catalog star; `body` is ignored when `star` is set. Pass an IANA `timezone` to also receive the observer-local time. This server does not geocode — resolve a place name to latitude/longitude upstream first.

The one-call "what is up right now" answer. For an observer location and instant, iterate every naked-eye solar-system body (and, with include_stars, the bundled bright stars), compute altitude and azimuth, keep those above the horizon, rank them brightest-and-highest first, and attach a plain-language visibility note to each, along with its angular distance from the Sun. The whole sky is gated by the Sun's altitude into daylight / civil / nautical / astronomical twilight / dark, returned alongside the list, and each note says when daylight, civil twilight, or the Sun's glare hides or dims that body. `time` is a single evaluation instant, not a window — for "tonight" pass a time after astronomical dusk (use astronomy_get_rise_set on the sun to find it). Default elevation 0 m; use min_altitude to skip objects grazing the horizon. This server does not geocode — resolve coordinates upstream first; pass an IANA timezone for observer-local times on each body.