# chuk-mcp-celestial
[](https://www.python.org/downloads/)
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, planetary positions/events,
and all-sky summaries 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!](https://celestial.chukai.io/mcp)** - 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 (included by default)
- **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](https://time.chukai.io/mcp) and [weather](https://weather.chukai.io/mcp) 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:
```json
{
"mcpServers": {
"celestial": {
"url": "https://celestial.chukai.io/mcp"
}
}
}
```
### Option 2: Install via uvx (No Installation Required)
Run directly without installing:
```json
{
"mcpServers": {
"celestial": {
"command": "uvx",
"args": ["chuk-mcp-celestial"]
}
}
}
```
### Option 3: Install Locally
```bash
# 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
```
Skyfield and NumPy are included by default — all 7 tools work out of the box.
**With S3 artifact storage (optional):**
```bash
pip install "chuk-mcp-celestial[s3]"
```
Then configure in your MCP client:
```json
{
"mcpServers": {
"celestial": {
"command": "chuk-mcp-celestial"
}
}
}
```
**Optional: Configure hybrid provider mode** (create `celestial.yaml`):
```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
```bash
# No installation required (runs directly)
uvx chuk-mcp-celestial
# Or install from PyPI
uv pip install chuk-mcp-celestial
# Or install from source with dev tools
git clone https://github.com/chuk-ai/chuk-mcp-celestial.git
cd chuk-mcp-celestial
uv pip install -e ".[dev]"
```
### Claude Desktop Configuration
```json
{
"mcpServers": {
"celestial": {
"url": "https://celestial.chukai.io/mcp"
}
}
}
```
Or run locally:
```json
{
"mcpServers": {
"celestial": {
"command": "uvx",
"args": ["chuk-mcp-celestial"]
}
}
}
```
### Run
```bash
# 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. |
Both providers are included by default — no extras needed.
## 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
### Sky Summary (1 tool)
| Tool | Description |
|------|-------------|
| `get_sky` | All-sky summary: every planet's position, moon phase, darkness check — one call |
## 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_SKY_PROVIDER` | No | `skyfield` | Provider for sky summary |
| `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:
```yaml
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
sky: skyfield # All-sky summary
```
## Development
```bash
# Install with 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:
```json
{
"mcpServers": {
"celestial": {
"url": "https://celestial.chukai.io/mcp"
}
}
}
```
### Docker
```bash
make docker-build
make docker-run
```
### Fly.io
```bash
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)
```json
{
"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](https://aa.usno.navy.mil/)
## Links
- [US Navy API Documentation](https://aa.usno.navy.mil/data/api)
- [MCP Protocol](https://modelcontextprotocol.io/)
