astronomy-mcp-server

<div align="center">
  <h1>@cyanheads/astronomy-mcp-server</h1>
  <p><b>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.</b>
  <div>7 Tools • 1 Resource • 1 Prompt</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.2.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/astronomy-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/astronomy-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/astronomy-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/astronomy-mcp-server/releases/latest/download/astronomy-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=astronomy-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYXN0cm9ub215LW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22astronomy-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fastronomy-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

---

## Tools

Seven tools — five form the keyless, offline, deterministic core (always registered); two are network-backed extensions that register only when their config gate is enabled.

| Tool | Description |
|:---|:---|
| `astronomy_get_sky_position` | Apparent position of one body or named star for an observer and instant — equatorial (RA/Dec), horizontal (alt/az), ecliptic, plus distance, magnitude, angular diameter, phase, and constellation. |
| `astronomy_get_rise_set` | Rise, set, and culmination times for a body at a location, with maximum altitude at transit. For the Sun, also the three twilight pairs (civil/nautical/astronomical). |
| `astronomy_get_moon_phase` | Moon phase for an instant: illuminated fraction, phase name, synodic age, phase angle, and the next four quarter phases with timestamps. |
| `astronomy_find_events` | Forward search for the next occurrences of one sky-event class: eclipses, equinoxes, solstices, moon quarters, oppositions, conjunctions, greatest elongations, and apsides. |
| `astronomy_list_visible` | The one-call "what's up right now" answer: every naked-eye body (and optional bright stars) above the horizon, ranked, annotated, and gated by the Sun's altitude into daylight/twilight/dark. |
| `astronomy_get_ephemeris` | *(gated extension)* Time-series ephemeris for a small body (asteroid/comet) or spacecraft via JPL Horizons — covers what the in-process major-body set cannot. Off by default. |
| `astronomy_get_satellite_passes` | *(gated extension)* Visible passes of a satellite (by NORAD ID) over an observer, from a CelesTrak TLE propagated with SGP4 in-process. Off by default. |

This server computes geometry — where a body is, when an event happens — not astrophysics. The core wraps [`astronomy-engine`](https://github.com/cosinekitty/astronomy) (sub-arcminute accuracy, ≈1900–2100), so given the same `(body, time, observer)` every core tool returns identical output with no network, no rate limit, and no API key. It does not geocode: resolve a place name to latitude/longitude upstream (e.g. via an OpenStreetMap server) and pass an IANA `timezone` to receive observer-local times alongside UTC.

### `astronomy_get_sky_position`

Apparent topocentric position of one solar-system body or a named bright star.

- Equatorial (RA/Dec), refraction-corrected horizontal (altitude/azimuth), and ecliptic coordinates in one call
- Distance, apparent magnitude, angular diameter, phase angle, illuminated fraction, and the constellation the body falls in
- Parallax- and aberration-corrected for the observer; default elevation 0 m, default time now
- Supply `star` (e.g. `"Sirius"`, `"Polaris"`) instead of `body` to target a catalog star; `star` takes precedence over `body`
- `null` magnitude / angular diameter / phase fields where the engine cannot compute them — never fabricated

---

### `astronomy_get_rise_set`

Rise, set, and culmination times, with twilight for the Sun.

- Searches forward from `start` and returns the next `count` cycles (default 1, max 31)
- For `body: "sun"`, bundles 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"
- Circumpolar / never-rises situations are reported as `null` rise/set fields with an explanatory `note` rather than an error — the fact is the answer
- Optional observer-local times when an IANA `timezone` is supplied

---

### `astronomy_find_events`

Forward search across nine event classes under one `event` enum.

- `solar_eclipse`, `lunar_eclipse`, `equinox`, `solstice`, `moon_quarter`, `opposition`, `conjunction`, `max_elongation`, `perigee_apogee`
- Solar eclipses require an observer (`latitude`/`longitude`) and report local visibility and contact times; lunar eclipses are geocentric and need no location
- The body-relative events (`opposition`, `conjunction`, `max_elongation`, `perigee_apogee`) require a `body`, gated to the bodies each event exists for: `opposition` to the superior planets (mars through pluto), `conjunction` to any planet, `max_elongation` to mercury and venus, `perigee_apogee` to the moon, earth, or a planet
- `perigee_apogee` on `earth` returns its perihelion and aphelion; `conjunction` on mercury or venus returns both the inferior and superior passes, labelled by `conjunction_kind`
- Returns the next `count` occurrences (default 1, max 20)

---

### `astronomy_list_visible`

The workflow flagship — one call returns a ranked, condition-gated "what's up" list.

- Iterates every naked-eye solar-system body (and, with `include_stars`, the bundled bright stars), keeps those above the horizon, and ranks them brightest-and-highest first
- Attaches a plain-language `visibility_note` to each body, computed from real magnitude and altitude — no synthetic score
- Returns the whole-sky condition (`daylight` / `civil_twilight` / `nautical_twilight` / `astronomical_twilight` / `dark`) and the Sun's altitude alongside the list
- `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)
- Use `min_altitude` to skip objects grazing the horizon

---

### `astronomy_get_ephemeris` *(gated extension)*

Time-series ephemeris for a small body or spacecraft via the keyless JPL Horizons API. Registered only when `ASTRONOMY_ENABLE_HORIZONS` is set.

- Covers asteroids, comets, and spacecraft the in-process major-body engine cannot see
- The designation is passed to Horizons verbatim and must resolve to a single record:
  - **Numbered asteroid** — trailing-semicolon record lookup: `"433;"` (Eros), `"1;"` (Ceres)
  - **Periodic comet** — DES + closest-apparition flag: `"DES=1P;CAP"` (Halley), `"DES=2P;CAP"` (Encke)
  - **Spacecraft** — negative SPK-ID: `"-48"` (Hubble)
  - A bare name like `"433 Eros"` or `"1P/Halley"` returns no match or an ambiguous record list and is rejected. Look up designations at [ssd.jpl.nasa.gov/tools/sbdb_lookup.html](https://ssd.jpl.nasa.gov/tools/sbdb_lookup.html).
- `start`/`stop` are ISO 8601 UTC and `stop` must be after `start`; `step` is a positive count plus a unit of `m`, `h`, `d`, `mo`, or `y` (`"10m"`, `"1h"`, `"1d"`)
- Supplying observer `latitude`/`longitude` yields topocentric coordinates and adds alt/az — pass both or neither; one alone is rejected rather than silently downgraded to a geocentric query
- Large spans truncate inline at 200 rows, and the disclosure carries the instant the returned rows end at. Re-call with `start` at that instant, or split the range into smaller adjacent spans — keep the same `step` and repeat until `truncated` is `false`, which reconstructs every sample. Widening the step discards samples the original range asked for

---

### `astronomy_get_satellite_passes` *(gated extension)*

Visible passes of a satellite over an observer. Registered only when `ASTRONOMY_ENABLE_SATELLITES` is set.

- Fetches the current TLE from CelesTrak by NORAD catalog number (e.g. `25544` for the ISS) and propagates it with SGP4 in-process
- Returns each pass's rise, peak, and set times with azimuths and the peak elevation
- Only naked-eye-plausible passes are returned — the satellite must be sunlit at peak while the observer's sky is dark
- Every returned pass rises inside the requested window. A pass already underway at `start` is omitted rather than reported with `start` as its `rise_utc`; move `start` earlier to see it. A pass rising exactly at `start` is kept, so feeding a reported `rise_utc` back as `start` never loses it
- An element set that will not propagate to the window is rejected by name — as a reentry when the window sits near the element set's epoch, otherwise as a `start` too