mcp-stargazing

Calculate the altitude, rise, and set times of celestial objects (Sun, Moon, planets, stars, and deep-space objects) for any location on Earth, with optional light pollution analysis.

Features

Altitude/Azimuth Calculation: Get elevation and compass direction for any celestial object.
Rise/Set Times: Determine when objects appear/disappear above the horizon.
Light Pollution Analysis: Load and analyze light pollution maps (GeoTIFF format).
Code Execution Ready:
- Serializable Returns: All tools return JSON-serializable data (ISO strings for dates), making them directly usable by LLMs.
- Pagination: analysis_area supports paging (page, page_size) to handle large datasets efficiently.
- Standardized Responses: Uniform response format { "data": ..., "_meta": ... } for better observability and error handling.
Performance:
- Async Execution: Non-blocking celestial calculations.
- Caching: Intelligent caching for Simbad queries and regional analysis.
- Proxy Support: Native support for HTTP/HTTPS proxies (useful for downloading astronomical data).
Time Zone Aware: Works with local or UTC times.
Data Driven: Integrated database of 10,000+ deep-sky objects (Messier & NGC) for smart recommendations.

Installation

This project uses uv for dependency management.

Local Installation

Install uv:
```
pip install uv
```
Sync dependencies:
```
uv sync
```
This will create a virtual environment in .venv and install all dependencies defined in pyproject.toml.
Activate the environment:
```
source .venv/bin/activate
```
Initialize Data (Required for Nightly Planner): This downloads the latest Messier and NGC catalog data to src/data/objects.json.
```
python scripts/download_data.py
```
Note: If you are behind a firewall, ensure HTTP_PROXY env var is set before running this script.

Docker Installation

You can also run the server using Docker, which handles all dependencies and data initialization automatically.

Build the image:

docker build -t mcp-stargazing .

Note: If you are behind a proxy, pass the proxy URL during build:

docker build --build-arg HTTP_PROXY=http://127.0.0.1:7890 -t mcp-stargazing .

Run the container:

# Basic run (SHTTP mode on port 3001)
docker run -p 3001:3001 mcp-stargazing

# With Environment Variables
docker run -p 3001:3001 \
  -e QWEATHER_API_KEY=your_key \
  -e STARGAZING_DB_CONFIG=your_db_config \
  mcp-stargazing

MCP Server Usage

Start the MCP server to expose tools to AI agents or other clients.

1. Environment Setup

Create a .env file or export variables:

# Required for weather tools
export QWEATHER_API_KEY="your_api_key"

# Optional: Proxy for downloading astronomical data (Simbad/IERS)
# Highly recommended if you are in a restricted network environment
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

2. Start Server

Streamable HTTP (SHTTP) mode (Recommended for most agents):

# Basic start
python -m src.main --mode shttp --port 3001 --path /shttp

# With proxy explicitly passed (overrides env vars)
python -m src.main --mode shttp --port 3001 --path /shttp --proxy http://127.0.0.1:7890

SSE mode:

python -m src.main --mode sse --port 3001 --path /sse

3. Response Format

All tools return data in a standardized JSON format:

{
  "data": {
    // Tool-specific return data
    "altitude": 45.5,
    "azimuth": 180.0
  },
  "_meta": {
    "version": "1.0.0",
    "status": "success"
  }
}

4. Available Tools

get_celestial_pos: Calculate altitude/azimuth.
get_celestial_rise_set: Calculate rise/set times (Returns ISO strings).
get_moon_info: Detailed moon phase, illumination, and age.
get_visible_planets: List of all planets currently above the horizon with positions.
get_constellation: Find the position (Alt/Az) of a constellation center.
get_nightly_forecast: Smart planner returning curated list of best objects to view tonight (Planets + Deep Sky).
get_weather_by_name / get_weather_by_position: Fetch current weather.
get_local_datetime_info: Get current local time information.
analysis_area: Find best stargazing spots in a region.
- Inputs: top_left, bottom_right, time, page, page_size.
- Returns: List of spots with viewing conditions, plus pagination metadata (total, resource_id).

Examples

Nightly Planner: python examples/nightly_forecast_demo.py
- Shows a curated list of planets and deep-sky objects visible tonight, accounting for moonlight.
Visible Planets: python examples/visible_planets_demo.py
- Lists which planets are currently up.
Moon Info: python examples/moon_phase_demo.py
- Prints a 30-day moon phase calendar.
Orchestration: python examples/code_execution_orchestration.py
- Demonstrates a full workflow: Get time -> Get Celestial Pos -> Check Weather -> Find Spots.
- Shows how to handle the standardized response format programmatically.
Pagination: python examples/pagination_demo.py
- Demonstrates fetching large result sets page by page using the resource_id.

Project Structure

The project is modularized for better maintainability and code execution support:

.
├── src/
│   ├── functions/            # Tool implementations grouped by domain
│   │   ├── celestial/        # Celestial calculations (pos, rise/set)
│   │   ├── weather/          # Weather API integration
│   │   ├── places/           # Location and area analysis
│   │   └── time/             # Time utilities
│   ├── cache.py              # Caching logic for analysis results
│   ├── response.py           # Standardized response formatting
│   ├── server_instance.py    # FastMCP server instance (avoids circular imports)
│   ├── main.py               # Entry point and tool registration
│   ├── celestial.py          # Core astronomy logic (Astropy wrappers)
│   ├── placefinder.py        # Grid analysis logic
│   └── qweather_interaction.py # Weather API client
├── tests/                    # Unified test suite
│   ├── test_celestial.py
│   ├── test_weather.py
│   ├── test_serialization.py # Validates JSON return formats
│   └── test_integration.py   # End-to-end flow tests
├── examples/                 # Usage examples
├── docs/                     # Documentation and improvement plans
└── pyproject.toml            # Project configuration and dependencies

Testing

Run the unified test suite:

pytest tests/

Key tests include:

test_serialization.py: Ensures all tools return valid JSON with the correct schema.
test_integration.py: Mocks external APIs to verify the entire toolchain.

Contributing

Follow the Code Execution with MCP best practices.
Ensure all new tools return standard JSON responses using src.response.format_response.
Add tests in tests/ for any new functionality.