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.

Related MCP server: Celestial Position MCP Server

Installation

This project uses uv for dependency management.

Local Installation

1. Install :

   pip install uv

2. Sync dependencies:

   uv sync

   This will create a virtual environment in .venv and install all dependencies defined in pyproject.toml.

3. Activate the environment:

   source .venv/bin/activate

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

Docker Installation

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

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

2. 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:

2. Start Server

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

SSE mode:

3. Response Format

All tools return data in a standardized JSON format:

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

Testing

Run the unified test suite:

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

1. Follow the Code Execution with MCP best practices.

2. Ensure all new tools return standard JSON responses using src.response.format_response.

3. Add tests in tests/ for any new functionality.