Celestial

You run the chuk-mcp-celestial server to access US Navy celestial data such as moon phases, rise/set times, eclipses, and Earth’s seasons. You can use a hosted version for instant testing, run locally with your own data, or execute via uvx for a zero-install experience. This guide shows practical steps to start, configure, and use the MCP server across common deployment options.

How to use

Choose a connection method and use an MCP client to ask questions like when the next full moon occurs, when the sun rises in a location, or whether a solar eclipse will be visible from a given place. You can mix providers to balance speed and accuracy, and you can pair celestial data with time and weather services for richer answers.

How to install

Prerequisites: you need Python installed and an MCP client capable of talking to an MCP server. You also have options for hosted, uvx, or local installation.

# Option A: Use Hosted Version (no installation)
# The hosted MCP URL is available for immediate testing
# No code execution required; you connect your client to the hosted endpoint

Hosted version (recommended for quick tests)

You can point your MCP client to the hosted endpoint and start querying celestial data right away.

{
  "mcpServers": {
    "celestial": {
      "url": "https://celestial.chukai.io/mcp"
    }
  }
}

Install via uvx (no local installation)

Run directly without installing dependencies on your system. This option keeps everything self-contained.

{
  "mcpServers": {
    "celestial": {
      "command": "uvx",
      "args": ["chuk-mcp-celestial"]
    }
  }
}

Install locally (full setup)

Install the server and its dependencies on your machine. You can use pip, uv, or pipx for isolated installs.

# Basic Installation (Navy API only)
pip install chuk-mcp-celestial

# Or with uv (recommended)
uv pip install chuk-mcp-celestial

# Or with pipx (isolated installation)
pipx install chuk-mcp-celestial

Optional: configure hybrid provider mode

Create a celestial.yaml to mix providers for different tools, balancing speed and offline capabilities.

# celestial.yaml
# Use Skyfield for fast queries, Navy API for everything else
default_provider: navy_api
providers:
  moon_phases: skyfield     # 28x faster
  earth_seasons: skyfield   # 33x faster

Quick start for local configuration and usage

After you install, configure your MCP client to target the local server and start asking questions like sunrise times, moon phases, or eclipses.

{
  "mcpServers": {
    "celestial": {
      "command": "chuk-mcp-celestial"
    }
  }
}

Example questions you can ask

• When is the next full moon? - What time does the sun rise in Seattle tomorrow? - Are there any solar eclipses visible from New York in 2024? - When are the equinoxes this year?

Using with mcp-cli

Test the server interactively with the mcp-cli client by pointing it to the hosted or local server.

uv run mcp-cli --server https://celestial.chukai.io/mcp --provider openai --model gpt-4o-mini

As a Python library

You can use the provided Python APIs to fetch moon phases, sun/moon data, eclipse data, and earth seasons. Import the functions you need, call them with your parameters, and process the typed results.

import asyncio
from chuk_mcp_celestial.server import get_moon_phases, get_sun_moon_data, get_solar_eclipse_by_date, get_earth_seasons

async def main():
    phases = await get_moon_phases(date="2024-12-01", num_phases=4)
    for phase in phases.phasedata:
        print(f"{phase.phase}: {phase.year}-{phase.month:02d}-{phase.day:02d} at {phase.time} UT")

    data = await get_sun_moon_data(date="2024-12-21", latitude=47.60, longitude=-122.33, timezone=-8)
    print(data.properties.data.curphase)

asyncio.run(main())

Notes on configuration and deployment

You can configure providers, storage backends, and ephemeris files to optimize performance and offline capabilities. Ephemeris data is stored via chuk-virtual-fs with options for local, memory, or S3 storage. If you use S3, you can download ephemeris files to your chosen backend and adjust storage settings in your configuration.

Available tools

get_moon_phases

Fetch upcoming moon phases from a start date for a specified count, returning a MoonPhasesResponse with phasedata

get_sun_moon_data

Get sun and moon rise/set/transit times, twilight, and moon phase for a given date and location, returning a OneDayResponse

get_solar_eclipse_by_date

Return local solar eclipse circumstances for a given date and location as a SolarEclipseByDateResponse

get_earth_seasons

Return Earth's seasons and orbital events for a given year as a SeasonsResponse

hybrid_provider_example

Demonstrates combining Skyfield and Navy API providers to optimize performance