How do I use chuk-mcp-celestial?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@chuk-mcp-celestial When is the next full moon and what time does the sun rise in Seattle tomorrow?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

chuk-mcp-celestial

Python 3.11+

Astronomical & Celestial Data MCP Server

An MCP (Model Context Protocol) server providing moon phases, sun/moon rise/set times, solar eclipse predictions, Earth's seasons, and planetary positions/events from the US Navy Astronomical Applications Department API and local Skyfield calculations.

This is a demonstration project provided as-is for learning and testing purposes.

🌐 Try it now - Hosted version available! - No installation required.

Features

🌙 Comprehensive Celestial Data:

Moon phases with exact timing (New Moon, First Quarter, Full Moon, Last Quarter)
Sun and moon rise/set/transit times for any location
Solar eclipse predictions with local circumstances
Earth's seasons (equinoxes, solstices, perihelion, aphelion)
Planetary positions (altitude, azimuth, distance, magnitude, constellation, RA/Dec, elongation, visibility)
Planetary events (rise, set, transit times)

⚡ Flexible Providers:

Navy API - Authoritative US Navy data, all features
Skyfield - 28x faster, offline calculations, research-grade accuracy
Hybrid mode - Mix providers per-tool (e.g., Skyfield for moon phases, Navy for eclipses)
S3 storage - Cloud-based ephemeris storage via chuk-virtual-fs
Artifact storage - Computation results persisted via chuk-artifacts (S3, filesystem, memory)
GeoJSON output - Location-based responses follow GeoJSON Feature spec

🔒 Type-Safe & Robust:

Pydantic v2 models for all responses - no dictionary goop!
Enums for all constants - no magic strings!
Full async/await support with httpx
Comprehensive error handling

🔗 Multi-Server Integration:

Works seamlessly with time and weather servers
Combine celestial + time + weather for comprehensive astronomical intelligence
Answer complex questions like "Will the moon be visible tonight with current weather?"

✅ Quality Assured:

70%+ test coverage with pytest
GitHub Actions CI/CD
Automated releases to PyPI
Type checking with mypy
Code quality with ruff

Installation

Comparison of Installation Methods

Method	Setup Time	Requires Internet	Updates	Best For
Hosted	Instant	Yes	Automatic	Quick testing, production use
uvx	Instant	Yes (first run)	Automatic	No local install, always latest
Local	1-2 min	Only for install	Manual	Offline use, custom deployments

Option 1: Use Hosted Version (Recommended)

No installation needed! Use our public hosted version:

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

Option 2: Install via uvx (No Installation Required)

Run directly without installing:

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

Option 3: Install Locally

Basic Installation (Navy API only):

# With pip 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

With Skyfield Support (offline calculations, 28x faster):

# Install with Skyfield and S3 support pip install "chuk-mcp-celestial[skyfield]" # Or with uv uv pip install "chuk-mcp-celestial[skyfield]" # Download ephemeris files (one-time setup) python scripts/download_ephemeris.py --backend local

Then configure in your MCP client:

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

Optional: Configure hybrid provider mode (create 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

Install

# No installation required (runs directly) uvx chuk-mcp-celestial # Or install from PyPI uv pip install chuk-mcp-celestial # Or install from source git clone https://github.com/chuk-ai/chuk-mcp-celestial.git cd chuk-mcp-celestial uv pip install -e ".[dev]"

Claude Desktop Configuration

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

Or run locally:

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

Run

# STDIO mode (Claude Desktop, mcp-cli) chuk-mcp-celestial stdio # HTTP mode (API access) chuk-mcp-celestial http --port 8080

Supported Providers

Provider	Speed	Offline	Features
Navy API (default)	~700ms	No	Moon, sun/moon, eclipses, seasons. Official US government source.
Skyfield	~25ms	Yes	Moon phases, seasons, planet position, planet events. JPL ephemeris.

Install Skyfield support:

uv pip install "chuk-mcp-celestial[skyfield]"

Tools

Moon Phases (1 tool)

Tool	Description
`get_moon_phases`	Upcoming moon phases with exact timing (UT1)

Sun & Moon (1 tool)

Tool	Description
`get_sun_moon_data`	Rise/set/transit times, twilight, moon phase, illumination for a location

Solar Eclipses (2 tools)

Tool	Description
`get_solar_eclipse_by_date`	Local eclipse circumstances (type, magnitude, obscuration, timing)
`get_solar_eclipses_by_year`	All solar eclipses in a year

Earth Seasons (1 tool)

Tool	Description
`get_earth_seasons`	Equinoxes, solstices, perihelion, aphelion for a year

Planets (2 tools)

Tool	Description
`get_planet_position`	Altitude, azimuth, distance, magnitude, constellation, RA/Dec, elongation, visibility
`get_planet_events`	Rise, set, and transit times for a planet on a given date

Supported: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto

Environment Variables

Variable	Required	Default	Description
`CELESTIAL_PROVIDER`	No	`navy_api`	Default provider
`CELESTIAL_MOON_PHASES_PROVIDER`	No	default	Provider for moon phases
`CELESTIAL_EARTH_SEASONS_PROVIDER`	No	default	Provider for Earth seasons
`CELESTIAL_PLANET_POSITION_PROVIDER`	No	`skyfield`	Provider for planet position
`CELESTIAL_PLANET_EVENTS_PROVIDER`	No	`skyfield`	Provider for planet events
`CELESTIAL_CONFIG_PATH`	No	—	Path to celestial.yaml
`SKYFIELD_STORAGE_BACKEND`	No	`s3`	Ephemeris storage: `local`, `s3`, `memory`
`SKYFIELD_S3_BUCKET`	No	`chuk-celestial-ephemeris`	S3 bucket for ephemeris
`NAVY_API_TIMEOUT`	No	`30.0`	Request timeout (seconds)

Hybrid Provider Mode

Create celestial.yaml to mix providers per-tool:

default_provider: navy_api providers: moon_phases: skyfield # 28x faster, offline earth_seasons: skyfield # 33x faster, offline sun_moon_data: navy_api # Full features solar_eclipse_date: navy_api solar_eclipse_year: navy_api planet_position: skyfield # Only provider with planet support planet_events: skyfield

Development

# Install dev dependencies uv pip install -e ".[dev]" # Run tests make test # Run tests with coverage make test-cov # Lint and format make lint make format # All checks make check

Deployment

Hosted Version

No installation required:

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

Docker

make docker-build make docker-run

Fly.io

fly launch fly secrets set AWS_ACCESS_KEY_ID=your_key AWS_SECRET_ACCESS_KEY=your_secret make fly-deploy

Cross-Server Workflows

chuk-mcp-celestial integrates with the broader chuk MCP ecosystem:

Celestial + Time — Timezone-aware astronomy (sunrise in local time, time until next event)
Celestial + Weather — Observation planning (moon phase + cloud cover forecast)
Celestial + Tides — Coastal photography (golden hour + tide level)
Celestial + Weather — Eclipse viewing (eclipse visibility + weather forecast)

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

License

Apache License 2.0 - See LICENSE for details.

Credits

Built on chuk-mcp-server
Data provided by US Navy Astronomical Applications Department

chuk-mcp-celestial

chuk-mcp-celestial

Features

Installation

Comparison of Installation Methods

Option 1: Use Hosted Version (Recommended)

Option 2: Install via uvx (No Installation Required)

Option 3: Install Locally

Quick Start

Install

Claude Desktop Configuration

Run

Supported Providers

Tools

Moon Phases (1 tool)

Sun & Moon (1 tool)

Solar Eclipses (2 tools)

Earth Seasons (1 tool)

Planets (2 tools)

Environment Variables

Hybrid Provider Mode

Development

Deployment

Hosted Version

Docker

Fly.io

Cross-Server Workflows

License

Credits

Links

Resources

New MCP Servers

Latest Blog Posts

MCP directory API