astronomy-mcp-server: get small-body ephemeris
astronomy_get_ephemerisFetch 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.
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": {
"designation": "<designation>"
},
"name": "astronomy_get_ephemeris"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| step | No | Step size as a positive count up to 2147483647 plus a unit of m (minutes), h (hours), d (days), mo (months), or y (years), e.g. "10m", "1h", "1d". Default "1h". | 1h |
| stop | No | Ephemeris stop as an ISO 8601 UTC string in years 0100 through 9999, at or after start — equal to start returns the single row at that instant. Defaults to 24 hours after start. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| start | No | Ephemeris start as an ISO 8601 UTC string, e.g. "2024-01-01T00:00:00Z", in years 0100 through 9999 — the calendar years JPL Horizons reads. Dates are Gregorian, extended before 1582. 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 — supply together with longitude for topocentric coordinates and alt/az. Supplying one without the other is rejected. | |
| elevation | No | Observer elevation in meters above sea level. Default 0. With latitude and longitude it must be greater than -20000 and less than 40000000 — the observer altitudes Horizons accepts; a geocentric request ignores it. | |
| longitude | No | Observer longitude in decimal degrees. Supply together with latitude; one without the other is rejected. | |
| designation | Yes | JPL Horizons target, passed verbatim — use a form that resolves to one record. Numbered asteroid: trailing-semicolon record lookup, e.g. "433;" (Eros), "1;" (Ceres). Periodic comet: DES + closest-apparition flag, e.g. "DES=1P;CAP" (Halley), "DES=2P;CAP" (Encke). Spacecraft: negative SPK-ID, e.g. "-48" (Hubble). A bare name like "433 Eros" (no match) or "1P/Halley" (several records) is rejected, and "Mars" (several major bodies) is rejected with their ID numbers listed — the planet is "499" — but one matching a single object succeeds even when it is not the object meant — check `target_name` in the result. Earth ("399") is rejected, being the body the observer is on, and so is a name containing an apostrophe, which the Horizons search cannot match — "6P/d'Arrest" resolves as "DES=6P;CAP" — or any character outside printable ASCII, which Horizons refuses, such as an accent or a typographic apostrophe — "Šteins" resolves as "2867;". Look up designations at ssd.jpl.nasa.gov/tools/sbdb_lookup.html. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The inline row cap that was applied. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of ephemeris rows returned. | |
| notice | No | Caveats on the returned series — how to retrieve rows omitted by the cap, and whether any rows were dropped. Absent when the whole span came back intact. | |
| points | No | Time-series of positions, one per step, in chronological order. | |
| dropped | No | Rows Horizons returned that carried no usable time, position, or distance and were dropped. Present only when at least one row was dropped, in which case the series has gaps and is shorter than the requested step count. | |
| truncated | No | True when the requested span continues past the returned rows; the notice names the start to resume from. | |
| designation | No | The body designation echoed from the request. | |
| target_name | No | The object JPL Horizons resolved the designation to, from its 'Target body name' header — compare it with the intended object, since a bare name can resolve to a different one. Absent when Horizons' response names no target. |