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. Horizons is asked for refracted elevation on a topocentric request, so altitude_degrees carries the same refraction correction the offline core tools report
• Large spans truncate inline at 200 rows. The disclosure names the instant the returned rows end at and the start to resume from — one step past it, because Horizons includes the start instant in its output, so resuming at the last row returned repeats it. Re-call with that start, or split the range into smaller adjacent spans — keep the same step and repeat until truncated is false, which concatenates back into the original series with no repeated 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.

• Identify the satellite by exactly one of norad_id (e.g. 25544 for the ISS) or name — both, or neither, is rejected before any request goes out
• Fetches the object's current GP element set from CelesTrak as OMM JSON and propagates it with SGP4 in-process. JSON rather than TLE because the legacy format cannot encode a catalog number above 99999, and CelesTrak already assigns six-digit numbers
• name is matched as a case-insensitive substring of the catalog name, so it resolves only when it picks out a single object — either the sole match, or the one match carrying that name outright. A broader query is rejected with the matching objects and their catalog numbers to choose from, capped at 20 and stating the full match count. The result echoes the query that resolved it as resolved_from_name
• 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
• A start further from the element set's epoch than the horizon below is rejected as out of range on that distance alone, and an element set that will not propagate to a window inside the horizon is rejected as a reentry — so an empty passes list means only "no visible passes in this window"
• start must be within about a month of the element set's epoch, which for a tracked object is hours old — so in practice within about a month of today. Past that the mean elements no longer describe the orbit, and SGP4 keeps returning positions built from them, which is why the horizon is enforced on the epoch distance rather than on whether the propagation succeeds
• NORAD catalog numbers and catalog names are found at celestrak.org or heavens-above.com
• Searches the next days (default 7, max 10); optional observer-local pass times

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 rounds hardest, since its per-body line is read at a glance down a list of dozens of bodies, and still carries every value's exact tail — no listed body needs a second call to recover its coordinates

Getting started

Public Hosted Instance

A public instance is available at https://astronomy.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "streamable-http",
      "url": "https://astronomy.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

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:

  sh

  Copy

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

• Run checks and tests:

  sh

  Copy

  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.