chuk-mcp-celestial

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! - 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 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

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

# 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):

pip install "chuk-mcp-celestial[s3]"

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 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

{
  "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

Both providers are included by default — no extras needed.

Tools

Moon Phases (1 tool)

Sun & Moon (1 tool)

Solar Eclipses (2 tools)

Earth Seasons (1 tool)

Planets (2 tools)

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

Sky Summary (1 tool)

Environment Variables

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
  sky: skyfield                # All-sky summary

Development

# 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:

{
  "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

Links

• US Navy API Documentation
• MCP Protocol