Astronomy MCP Server

@cyanheads/astronomy-mcp-server What's in the sky, computed offline — planet and moon positions, rise/set, phases, eclipses, and seasons for any place and time via MCP. STDIO or Streamable HTTP. 7 Tools • 1 Resource • 1 Prompt • 1 Skill

Public Hosted Server: https://astronomy.caseyjhand.com/mcp

Overview

Observational astronomy for any place and time: sky positions, rise/set and twilight times, moon phases, and the next eclipse, equinox, opposition, or conjunction — or just ask what's visible right now. Computed locally by astronomy-engine, with optional JPL Horizons ephemerides and satellite passes.

Tools

Resources

Tool-only clients get the same type, radius, and naked-eye fields inline from astronomy_get_sky_position.

Prompts

Skills

Plugin installs load it from skills/; MCP clients that support the Skills extension read it as skill://astronomy-guide/SKILL.md.

Design reference: docs/design.md.

Capability reference

astronomy_get_sky_position tool

• body (sun, moon, mercury … pluto) or star is required, with star winning when both are set; star resolves against a bundled 32-star catalog by common name or Bayer designation (Sirius, α CMa), and a miss fails as star_not_found listing the catalog
• Returns equatorial, refraction-corrected horizontal, and ecliptic coordinates plus magnitude, angular_diameter_arcsec, phase_angle_degrees, illuminated_fraction, sun_elongation_degrees, and constellation
• Solar-system bodies also carry body_metadata, the resource card's type, mean_radius_km, and naked_eye; a star has none

astronomy_get_rise_set tool

• One body searched forward from start (default now) for the next count cycles, default 1; 31 are served per call, and a count up to 366 returns the first 31 with a notice naming the start and count that continue the series
• Each cycle carries rise_utc, set_utc, transit_utc, and transit_altitude_degrees; a circumpolar or never-rising body gets null rise/set and a note instead of an error
• For body: "sun", twilight holds civil, nautical, and astronomical dusk/dawn pairs for the night after each cycle's day. When the first day begins after start, night_in_progress holds the preceding night, including polar nights without a sunset; the first cycle otherwise carries its own night. Each pair stays within that night, and times before start remain included

astronomy_get_moon_phase tool

• Geocentric: takes only time (default now) and an optional timezone
• Returns illuminated_fraction, phase_name, age_days, next_quarters, and phase_longitude_degrees (0 new, 180 full), which is not the phase_angle_degrees of astronomy_get_sky_position

astronomy_find_events tool

• One event (solar_eclipse, lunar_eclipse, equinox, solstice, moon_quarter, opposition, conjunction, max_elongation, perigee_apogee) and the next count occurrences, default 1; 20 are served per call, and a count up to 200 returns the first 20 with a notice naming the start and count that continue the series; searches stop at the end of 2100
• Body-relative events require body (body_required); a body the event doesn't apply to fails as body_not_supported, and conjunction with body2 takes the Moon or a planet different from body (invalid_body_pair otherwise) and reports separation_degrees
• Eclipses take an optional observer (latitude and longitude together, else incomplete_observer) that adds local_visible and contact_altitudes_degrees
• Eclipses are included when their peak is at or after start; their contacts may precede start

astronomy_list_visible tool

• Observer coordinates and one evaluation instant, time (default now, not a window); min_altitude (default 0) and include_stars (default false) shape the list
• Returns sky_condition (daylight, civil_twilight, nautical_twilight, astronomical_twilight, dark), sun_altitude_degrees, and bodies ranked brightest-and-highest first, each with a visibility_note that says when daylight, civil twilight, or Sun glare within 15° hides or dims it

astronomy_get_ephemeris tool

• designation is passed to Horizons verbatim ("433;" for a numbered asteroid, "DES=1P;CAP" for a periodic comet, a negative SPK-ID for a spacecraft); start defaults to now, stop to 24 h later, and step to "1h" (a count plus m, h, d, mo, or y); latitude and longitude together add alt/az
• Up to 200 rows per call; when truncated is true the notice names the start to resume from. target_name is the object Horizons resolved
• Fails as ambiguous_designation, observer_is_target, body_not_found, invalid_step, invalid_elevation, time_out_of_range, or request_rejected, each naming the input to correct
• Registered only when ASTRONOMY_ENABLE_HORIZONS=true

astronomy_get_satellite_passes tool

• Exactly one of norad_id or name (ISS, Hubble/HST, and Tiangong/CSS resolve directly; other names are matched against CelesTrak, and an ambiguous one fails as ambiguous_satellite_name listing candidates); start must be within about a month of today, and days defaults to 7
• 10 days are searched per call; a days up to 30 returns the first 10 with a notice naming the start and days that continue the search
• Returns norad_id, satellite_name, and passes that are visible (sunlit, above 10° elevation, Sun below −6°), each with rise/peak/set times and azimuths, peak_altitude_degrees, duration_seconds, sunlit, and visible_start_utc/visible_end_utc
• Registered only when ASTRONOMY_ENABLE_SATELLITES=true

astronomy://body/{body} resource

• {body} is one of sun, moon, mercury … pluto, with name completion; anything else fails as unknown_body
• application/json card with body, name, type (star/planet/moon/dwarf), mean_radius_km, and naked_eye

astronomy_stargazing_plan prompt

• Arguments: location required; date (YYYY-MM-DD) optional, defaults to tonight
• Returns one user message that chains astronomy_get_rise_set (sun, then moon), astronomy_get_moon_phase, and astronomy_list_visible with include_stars, plus the geocoding and weather steps this server doesn't cover

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Astronomy-specific:

• Keyless, offline, deterministic core: the five core tools need no network, API key, or rate limit, and return the same answer for the same body, time, and observer
• Times outside the engine's high-accuracy span (≈1900–2100) fail as time_out_of_range; the Horizons tool is bounded by each target's own data span instead
• Times are ISO 8601 UTC, and a value with no zone is read as UTC; pass an IANA timezone (or set ASTRONOMY_DEFAULT_TIMEZONE) to get *_local fields alongside UTC. The server never infers a timezone from coordinates
• No geocoding: resolve a place name to latitude/longitude and a timezone upstream, then pass the coordinates (elevation defaults to 0 m)
• The two opt-in extensions each carry their own timeout and retry; an upstream failure surfaces as horizons_unavailable or celestrak_unavailable and never falls back to core output

Agent-friendly output:

• Uncertainty preserved: magnitude, angular_diameter_arcsec, phase_angle_degrees, and illuminated_fraction are null where the engine can't compute them, rendered as "unavailable", never zeroed
• Deterministic visibility notes: visibility_note comes from real magnitude, altitude, sky condition, and Sun elongation, not a synthetic score
• Typed error contracts: each declared failure carries a typed reason and a recovery hint, so callers can correct and retry
• Exact values behind rounded text: `f