astronomy-mcp-server: find sky events
astronomy_find_eventsSearch 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"event": "<event>"
},
"name": "astronomy_find_events"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Target body — required for opposition, conjunction, max_elongation, and perigee_apogee; ignored otherwise. "earth" is accepted only for perigee_apogee, which returns its perihelion and aphelion. With `body2`, the Moon or a planet. | |
| body2 | No | Second body for a conjunction of two bodies: the Moon or a planet, different from `body`. Accepted only with event "conjunction", where it replaces the conjunction of `body` with the Sun by the conjunction of `body` and `body2` in ecliptic longitude seen from Earth's center. For the Moon meeting the Sun, search moon_quarter for the new moon. | |
| count | No | Number of forward occurrences to return. Default 1. At most 20 are computed per call; a count up to 200 returns the first 20 with a notice naming the `start` and `count` that continue the series. | |
| event | Yes | Which class of event to search for. | |
| start | No | Search start as an ISO 8601 UTC string, e.g. "2024-01-01T00:00:00Z". Eclipses are included when their peak is at or after start; earlier contacts may still be returned. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| latitude | No | Observer latitude in decimal degrees, supplied together with longitude. Optional for solar_eclipse and lunar_eclipse, where it adds local circumstances; omit both for a global solar search. Ignored by every other event. | |
| timezone | No | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. | |
| elevation | No | Observer elevation in meters above sea level. Default 0. | |
| longitude | No | Observer longitude in decimal degrees, supplied together with latitude. Optional for solar_eclipse and lunar_eclipse; ignored by every other event. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The per-call event cap that was applied. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of events returned when the cap applied. | |
| events | No | The next occurrences of the requested event class, in chronological order. | |
| notice | No | Why the list is shorter than the requested count: either the per-call cap held events back, and the notice names the exact `start` and `count` to re-call with, or the search reached the end of the supported span (2100). Absent when every requested occurrence came back. | |
| truncated | No | True when `count` exceeded the per-call cap and only the first events came back. | |
| totalCount | No | Number of event occurrences returned. |