Skip to main content
Glama

astronomy-mcp-server

by io.github.cyanheads

astronomy-mcp-server: get small-body ephemeris

astronomy_get_ephemeris
Read-onlyIdempotent

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) — a bare name like "433 Eros" or "1P/Halley" returns no match or an ambiguous record list and is rejected. Spacecraft take their negative SPK-ID. start and stop are ISO 8601 UTC and stop must be after start; 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
stepNoStep size as a positive count plus a unit of m (minutes), h (hours), d (days), mo (months), or y (years), e.g. "10m", "1h", "1d". Default "1h".1h
stopNoEphemeris stop as an ISO 8601 UTC string, and must be later than start. Defaults to 24 hours after start. A value with no zone designator is read as UTC, not the local zone of the server process.
startNoEphemeris start as an ISO 8601 UTC string, e.g. "2024-01-01T00:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process.
latitudeNoObserver latitude in decimal degrees — supply together with longitude for topocentric coordinates and alt/az. Supplying one without the other is rejected.
elevationNoObserver elevation in meters above sea level. Default 0.
longitudeNoObserver longitude in decimal degrees. Supply together with latitude; one without the other is rejected.
designationYesJPL 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" or "1P/Halley" fails. Look up designations at ssd.jpl.nasa.gov/tools/sbdb_lookup.html.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe inline row cap that was applied.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of ephemeris rows returned.
noticeNoCaveats 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.
pointsNoTime-series of positions, one per step, in chronological order.
droppedNoRows 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.
truncatedNoTrue when Horizons returned more rows than the inline cap.
designationNoThe body designation echoed from the request.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint, openWorldHint, and idempotentHint, but the description goes well beyond them: it reveals the tool is network-backed and rate-limited ('best-effort'), truncates at 200 rows, and explains the exact resume behavior (one step past the last row). It also notes that missing zones are interpreted as UTC. This is rich behavioral disclosure that complements, and does not contradict, the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place. It is front-loaded with the core purpose, then flows logically through designation format, time/interval syntax, observer parameters, and truncation behavior. No fluff or redundancy; it is dense with necessary guidance. The only minor downside is its length, which might require careful reading, but it is efficiently structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, network-backed tool with 7 parameters and an output schema, the description is exceptionally complete. It covers all critical usage aspects: designation encoding with examples, ISO time format and timezone handling, step unit rules, observer coordinate requirements, and the truncation resume mechanism with precise instructions. An agent has everything needed to call this tool correctly, including edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all 7 parameters with detailed descriptions, so the baseline is 3. The description adds significant value beyond the schema: it explains the designation format rules in depth (trailing semicolon, DES+CAP, negative SPK-ID), emphasizes the pairwise requirement for latitude/longitude, and describes the step unit semantics and default stop. It doesn't just repeat the schema; it clarifies pitfalls and edge cases.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb and resource: 'Fetch a time-series ephemeris for a small body (asteroid or comet) or spacecraft from JPL Horizons' and enumerates the returned quantities (RA/Dec, distance, magnitude, optional alt/az). It explicitly distinguishes itself from the in-process major-body set, so an agent can tell it apart from siblings without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states exactly when this tool is appropriate ('covers objects the in-process major-body set cannot') and gives precise, unambiguous invocation requirements: the designation format must resolve to a single Horizons record, with examples of what fails. It also explains when to supply observer coordinates and how to handle truncation via resume, leaving no ambiguity about usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All astronomy-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0
Disambiguation5/5

Each tool targets a clearly distinct aspect of astronomy: event lookup, ephemeris for small bodies, moon phase, rise/set times, satellite passes, sky position for bodies/stars, and a visible-objects summary. Even overlapping capabilities (e.g., get_sky_position vs. get_ephemeris) are separated by scope (single instant vs. time series, major bodies vs. small bodies). No ambiguity in choosing between tools.

Naming Consistency5/5

All tool names follow a consistent pattern: 'astronomy_' prefix + descriptive verb ('find', 'get', 'list') + object. The verbs are homogeneous (mostly 'get_', plus 'find_events' and 'list_visible'), and the snake_case style is uniform. Predictable and easy to navigate.

Tool Count5/5

Seven tools is a well-scoped number for an astronomy server. Each tool covers a distinct major query type, and none feel redundant or unnecessary. This is within the ideal 3–15 range and feels neither too thin nor too heavy.

Completeness5/5

The tool set covers the full range of common astronomy asks: positions, phases, events, rise/set, satellite passes, and a 'what's up' overview. Small-body ephemerides fill the gap for non-major objects. There are no obvious dead ends; an agent can answer most user questions with these tools alone.

Resources