astronomy-mcp-server

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.

This server computes geometry — where a body is, when an event happens — not astrophysics. The core wraps astronomy-engine (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.

• 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 far from it — so an empty passes list means only "no visible passes in this window"

• start must be within about a month of today: an element set describes the orbit for weeks around its epoch, and CelesTrak publishes only current ones

• NORAD catalog numbers are found at celestrak.org or heavens-above.com

• Searches the next days (default 7, max 10); optional observer-local pass times

Related MCP server: Precision astronomical ephemeris and planetary positions via the Swiss Ephemeris.

Resources and prompts

All resource data is also reachable via tools — astronomy_get_sky_position returns the same body metadata inline — so tool-only clients lose nothing. Design reference: docs/design.md.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation

• Unified error handling — handlers throw, framework catches, classifies, and formats

• Pluggable auth: none, jwt, oauth

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• STDIO and Streamable HTTP transports; the keyless core is Cloudflare Workers-portable (pure JS, no native deps)

Astronomy-specific:

• Keyless, offline, deterministic core — astronomy-engine is the source of truth for positional astronomy; no network, no rate limit, no API key for the five core tools

• Both UTC and observer-local time on every output when a timezone is supplied; the server never guesses a timezone from coordinates

• Bundled bright-star catalog so astronomy_list_visible and astronomy_get_sky_position answer for named stars

• Two gated extensions (off by default) reach beyond the major-body set — JPL Horizons small bodies and CelesTrak satellite passes — each with its own timeout/retry boundary; they degrade loudly and never silently fall back to the core

Agent-friendly output:

• Preserves uncertainty — magnitude, angular diameter, phase, and illumination are null (not 0, not omitted) when unavailable, and format() renders "unavailable" rather than inventing a value

• Server-computed visibility notes are deterministic prose from real magnitude and altitude — no synthetic confidence scores

• Typed error contracts with recovery hints (out-of-range time, missing observer/body, unresolved designation) so callers can correct and retry

• format() is content-complete on every tool — content[]-only clients see the same fields as structuredContent clients, and the same numbers: a value reads as a rounded display figure followed by its exact counterpart in brackets, e.g. RA 4.4116 h [4.411597993526305], dropped when the rounding already round-trips. astronomy_list_visible is the one scan surface, so its per-body line keeps only the distance's exact tail; astronomy_get_sky_position takes any body listed there and returns the same field set with every exact value

Getting started

Add the following to your MCP client configuration file. The five core tools need no configuration; set ASTRONOMY_ENABLE_HORIZONS and/or ASTRONOMY_ENABLE_SATELLITES to true to register the gated extensions.

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/astronomy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/astronomy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/astronomy-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).

• No API key required — both the offline core and the two keyless extensions (JPL Horizons, CelesTrak) need no credentials.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/astronomy-mcp-server.git

2. Navigate into the directory:

cd astronomy-mcp-server

3. Install dependencies:

bun install

Configuration

All configuration is optional and validated at startup via Zod schemas in src/config/server-config.ts. The core runs with no configuration at all.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t astronomy-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio astronomy-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/astronomy-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

• Register new tools and resources in the createApp() arrays in src/index.ts

• Normalize raw engine/API values to the domain type; preserve uncertainty as null and never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.