CelestialMCP Server

Provides real-time celestial data and tools to query object positions, rise/set times, and star-hopping paths using local catalogs.

typescript

1

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "rkm1999-celestialmcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/your/CelestialMCP/project/dist/index.js"
      ]
    }
  }
}

CelestialMCP is a specialized MCP server that provides real-time astronomical data and practical tools for exploring celestial objects. You can query current positions, coordinates, visibility, rise/transit/set times, and plan star hops using local catalogs. This makes it easy to integrate astronomy data into AI assistants or custom clients for observations and planning.

How to use

You interact with CelestialMCP through an MCP client. The server exposes three core tools you can invoke from your client: getCelestialDetails to retrieve detailed information about a specific object, listCelestialObjects to discover what objects are available, and getStarHoppingPath to generate a guided path from a bright star to a target object. All calculations are performed for a pre-configured observer location and the current system time unless you override those inputs in a call.

How to install

Follow these exact steps to install and run CelestialMCP on your machine.

# 1. Clone the repository
git clone https://github.com/Rkm1999/CelestialMCP
cd CelestialMCP

# 2. Install dependencies
npm install

# 3. Download Astronomical Catalogs (highly recommended)
npm run fetch-catalogs

# 4. Build the project
npm run build

# 5. Start the server
npm start

Configuration notes and catalogs

CelestialMCP uses a pre-configured observer location and current time for all calculations. By default, the observer location is Vancouver, Canada. You can adjust this in the configuration file to reflect your observing site.

// src/config.ts
export const OBSERVER_CONFIG = {
  latitude: 49.2827,
  longitude: -123.1207,
  altitude: 30,
  temperature: 15,
  pressure: 1013.25
};

Using with Claude Desktop (local development)

For local development with Claude Desktop, run the following sequence to install, fetch catalogs, build, and start the server. This enables the CelestialMCP tools to be available to Claude.

# Install dependencies
npm install

# Fetch star and deep sky object catalogs (IMPORTANT!)
npm run fetch-catalogs

# Build the project
npm run build

# Start the server
npm start

Available tools

getCelestialDetails

Retrieves comprehensive astronomical data for a specific celestial object, including current position, coordinates, visibility, rise/transit/set times, and, for relevant objects, distance and illumination details.

listCelestialObjects

Lists known celestial objects, with optional filtering by category, to help you discover available queries before requesting details.

getStarHoppingPath

Calculates a star hopping sequence from a bright starting star to a target object, using a specified field of view and magnitude limits to guide manual observations.