Skip to main content
Glama
enesjakozh
Rkm1999

Celestial Position MCP Server

by Rkm1999
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

CelestialMCP

A Model Context Protocol (MCP) server designed for AI assistants like Claude. It provides tools to access astronomical data, such as celestial object positions, rise/set times, visibility, and catalog information.

Overview

CelestialMCP is built with the mcp-framework and leverages the astronomy-engine library to provide accurate astronomical calculations. It offers several tools for determining positions of celestial objects, calculating their rise and set times, and listing available objects from star and deep sky object catalogs.

Features

  • Real-time Celestial Data: Access current astronomical data for a variety of objects.

  • Comprehensive Object Details: Retrieve equatorial and horizontal (altitude/azimuth) coordinates, visibility status, rise/transit/set times.

  • Specialized Data: For relevant objects, get distance (solar system objects), phase illumination (Moon and planets), and upcoming lunar phases (Moon).

  • Extensive Catalogs: Utilizes local catalogs for:

    • Solar system objects (Sun, Moon, planets).

    • Stars (e.g., from HYG database).

    • Deep Sky Objects (DSOs) including Messier, NGC, and IC objects.

  • Configurable Observer: All calculations are based on a pre-configured observer location (default: Vancouver, Canada) and the current system time.

  • Easy Catalog Updates: Includes a script to download and update comprehensive astronomical catalogs.

Tools

The server provides three primary tools for the AI to use:

  1. getCelestialDetails: Retrieves detailed astronomical information for a specific celestial object.

  2. listCelestialObjects: Lists available celestial objects known to the system, filterable by category.

  3. getStarHoppingPath: Calculates a star hopping path from a bright start star to a target celestial object.

Related MCP server: chuk-mcp-celestial

Setup and Installation

Prerequisites

  • Node.js (version >=18.19.0, as specified in package.json)

  • npm (usually comes with Node.js)

Steps

  1. Clone the repository (if you haven't already):

    git clone https://github.com/Rkm1999/CelestialMCP
cd CelestialMCP

  2. Install dependencies:

    npm install

  3. Download Astronomical Catalogs: This step is crucial for accessing a wide range of stars and deep sky objects.

    npm run fetch-catalogs

    This script downloads the HYG star database and the OpenNGC (New General Catalogue) deep sky object catalog into the data/ directory. If these files are not downloaded, the application will attempt to use sample_stars.csv and sample_dso.csv from the data/ directory if present. If no catalog files are found, the respective catalogs will be empty.

  4. Build the project: This compiles the TypeScript code to JavaScript.

    npm run build

  5. Start the server:

    npm start

    The MCP server will start, and the tools will become available to a connected AI assistant.

Using with Claude Desktop

To use CelestialMCP with Claude Desktop for local development, add the following configuration to your Claude Desktop config file:

# 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

Windows: %APPDATA%/Claude/claude_desktop_config.json MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "CelestialMCP": { "command": "node", // Or your node executable path "args":["/absolute/path/to/your/CelestialMCP/project/dist/index.js"] // Replace with the actual absolute path } } }

Catalog Data

The npm run fetch-catalogs script downloads:

  • hygdata_v41.csv: The HYG star database (approx. 120,000 stars).

  • ngc.csv: The OpenNGC catalog (approx. 14,000 deep sky objects).

These files are stored in the data/ directory. If these primary catalog files are not found, the application will attempt to load sample_stars.csv and sample_dso.csv if they exist in the data/ directory. For comprehensive data, running npm run fetch-catalogs is highly recommended.

Tool Usage

All astronomical calculations performed by these tools use the pre-configured observer location (see src/config.ts) and the current system time when the request is made.

1. getCelestialDetails

Purpose: Retrieves comprehensive astronomical data for a specific celestial object. This includes its current position (equatorial and horizontal coordinates), visibility (e.g., above/below horizon, visibility quality), rise/transit/set times for the current day, and, for relevant objects, distance from Earth, illumination phase, and upcoming lunar phases (for the Moon).

Parameters:

  • objectName (string): The name or catalog identifier of the celestial object. The tool can resolve common names (e.g., "Andromeda Galaxy") to their catalog IDs (e.g., "M31"). Examples: "Mars", "Sirius", "M42", "NGC 253", "Orion Nebula", "Moon", "Sun"

Example Claude Prompts:

  • "Get details for Jupiter from the configured location."

  • "What are the current coordinates of the Moon?"

  • "Tell me about the star Vega, including its rise and set times for today."

  • "Is the Whirlpool Galaxy (M51) visible tonight?"

  • "Show me information about the Sun's current position and rise/set times."

2. listCelestialObjects

Purpose: Lists celestial objects known to the system, which can then be queried using getCelestialDetails. Objects can be filtered by category. This helps in discovering what objects are available for querying.

Parameters:

  • category (string, optional): Filters the list of objects by a specific category. If omitted, it defaults to "all". Valid categories are:

    • planets: Solar System objects (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto).

    • stars: Named or cataloged stars.

    • messier: Objects from the Messier catalog (e.g., M1, M31).

    • ic: Objects from the Index Catalogue (e.g., IC 434).

    • ngc: Objects from the New General Catalogue (e.g., NGC 7000).

    • dso: All Deep Sky Objects (combines Messier, IC, NGC, and other DSOs like common named nebulae or galaxies not in these specific catalogs if available).

    • all: All available objects from all categories (default).

Example Claude Prompts:

  • "List all available Messier objects."

  • "What planets can I get information on?"

  • "Show me some bright stars I can look up using the stars category."

  • "List all NGC objects in the catalog."

  • "What deep sky objects (dso) are available?"

  • "Can you list all objects known to the system?"

3. getStarHoppingPath

Purpose: Calculates a star hopping path from a bright start star to a target celestial object. Each hop is within the specified Field of View (FOV). This tool helps observers manually locate dimmer objects by "hopping" from one recognizable star to another.

Parameters:

  • targetObjectName (string): The name or catalog identifier of the celestial object to find. Examples: "M13", "Andromeda Galaxy", "Mars", "NGC 7000"

  • fovDegrees (number, positive): The Field of View (FOV) of the user's equipment in degrees (e.g., binoculars, telescope eyepiece). Example: 5.0

  • maxHopMagnitude (number, optional, default: 8.0): The maximum (dimmest) stellar magnitude for stars to be included in the hopping path. Brighter stars have lower magnitude values. Example: 7.5

  • initialSearchRadiusDegrees (number, positive, optional, default: 20.0): The angular radius (in degrees) around the target object to search for a suitable bright starting star. Example: 25.0

  • startStarMagnitudeThreshold (number, optional, default: 3.5): The maximum (dimmest) magnitude for a star to be considered a good, bright "starting star" for the hop sequence. Example: 4.0

Example Claude Prompts:

  • "Find a star hopping path to M13 with a 5 degree FOV."

  • "Can you give me a star hop sequence to the Ring Nebula (M57) using an 8x50 binocular (FOV around 6 degrees) and stars no dimmer than magnitude 7?"

  • "I need to find NGC 253. My telescope has a 1 degree field of view. Find a path starting from a star brighter than magnitude 3, within 20 degrees of the target."

  • "Generate a star hopping guide to the Sombrero Galaxy, assuming a 2 degree FOV and max hop magnitude of 8.5."

Project Structure

CelestialMCP/
├── src/
│   ├── tools/                      # MCP Tools provided to the AI
│   │   ├── CelestialDetailsTool.ts   # Tool to get detailed info for an object
│   │   ├── ListCelestialObjectsTool.ts # Tool to list available objects
│   │   └── StarHoppingTool.ts        # Tool to calculate star hopping paths
│   ├── utils/                      # Utility functions
│   │   └── astronomy.ts            # Core astronomy calculations and catalog loading
│   ├── config.ts                   # Observer's location and atmospheric conditions configuration
│   └── index.ts                    # MCP Server entry point
├── scripts/
│   └── fetch-catalogs.js           # Script to download astronomical catalogs
├── data/                           # Directory for catalog data files (e.g., hygdata_v41.csv, ngc.csv)
│   ├── README.md                   # Information about data files
│   ├── sample_dso.csv            # Sample DSO data if full catalog isn't downloaded
│   └── sample_stars.csv          # Sample star data if full catalog isn't downloaded
├── package.json
└── tsconfig.json

Default Configuration

By default, the observer's location is set to Vancouver, Canada. You can change this in src/config.ts: This configuration is used for all calculations unless a tool specifically allows overriding it (current tools do not).

export const OBSERVER_CONFIG = {
  latitude: 49.2827,    // Observer latitude
  longitude: -123.1207, // Observer longitude
  altitude: 30,         // Observer altitude in meters
  temperature: 15,      // Default temperature in Celsius
  pressure: 1013.25     // Default pressure in hPa
};

License

MIT

Acknowledgements

  • astronomy-engine for core astronomical calculations

  • mcp-framework for the MCP server implementation

  • HYG Database for star data

  • OpenNGC for deep sky object data

Available Tools

3 tools
getCelestialDetailsA

Retrieves detailed astronomical information for a specified celestial object (e.g., planet, star, Messier object, NGC/IC object). Information includes current equatorial and horizontal (altitude/azimuth) coordinates, visibility status (above/below horizon), rise/transit/set times, and, where applicable, distance, phase illumination, and upcoming moon phases. All calculations are performed for the pre-configured observer location and the current system time. The tool automatically resolves common names (e.g., 'Andromeda Galaxy' to 'M31') and handles various catalog identifiers.

ParametersJSON Schema
NameRequiredDescriptionDefault
objectNameYesThe name or catalog identifier of the celestial object. Examples: 'Jupiter', 'Sirius', 'M31', 'NGC 7000', 'Crab Nebula'. The tool will attempt to resolve common names.

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key behaviors: automatic name resolution, pre-configured observer location and current time calculations, and the types of information returned. However, it doesn't mention potential limitations like accuracy constraints, failure modes for unresolvable names, or performance characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured in two sentences: the first states the purpose and comprehensive information returned, the second explains behavioral aspects like automatic resolution and calculation settings. Every sentence adds essential information with zero wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description does a reasonable job covering the tool's purpose, behavior, and parameter context. However, it doesn't describe the format or structure of returned information, which would be important for an agent to process the results effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage for the single parameter, the baseline is 3. The description adds value by explaining the tool's automatic name resolution capability ('resolves common names') and providing broader context about what types of celestial objects are supported, which complements the schema's examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Retrieves') and resource ('detailed astronomical information for a specified celestial object'), with specific examples of object types (planet, star, Messier object) and information returned (coordinates, visibility, times, distance, phases). It distinguishes from sibling tools by focusing on detailed information retrieval rather than pathfinding or listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: to get detailed astronomical information for a specific celestial object. It mentions automatic name resolution and pre-configured observer/time settings, but doesn't explicitly state when NOT to use it or name alternatives among sibling tools (e.g., use listCelestialObjects for browsing).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getStarHoppingPathC

Calculates a star hopping path from a bright start star to a target celestial object. Each hop is within the specified Field of View (FOV).

ParametersJSON Schema
NameRequiredDescriptionDefault
fovDegreesYesThe Field of View (FOV) of the user's equipment in degrees.
initialSearchRadiusDegreesYesThe angular radius around the target object to search for a suitable bright starting star. Default: 20.0 degrees.
maxHopMagnitudeYesThe maximum (dimmest) stellar magnitude for stars in the hopping path. Default: 8.0.
startStarMagnitudeThresholdYesThe maximum (dimmest) magnitude for a star to be a good, bright "starting star." Default: 3.5.
targetObjectNameYesThe name or catalog identifier of the celestial object to find (e.g., "M13", "Andromeda Galaxy", "Mars").

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the calculation process and FOV constraint, but lacks details on what the output looks like (e.g., path format, error handling), computational requirements, rate limits, or any side effects. For a tool with 5 parameters and no output schema, this leaves significant gaps in understanding how the tool behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured in two sentences: the first states the core purpose, and the second adds a key constraint. Every word earns its place, with no redundancy or fluff. It's appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, no annotations, no output schema), the description is incomplete. It explains what the tool does but not what it returns, how errors are handled, or practical considerations for use. Without annotations or output schema, users lack critical context about the tool's behavior and results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema fully documents all 5 parameters with clear descriptions and defaults. The description adds no additional parameter semantics beyond what's in the schema—it doesn't explain relationships between parameters (e.g., how FOV interacts with hop selection) or provide usage examples. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: calculating a star hopping path from a bright start star to a target celestial object, with hops constrained by Field of View. It specifies the verb ('calculates'), resource ('star hopping path'), and key constraint ('within the specified Field of View'). However, it doesn't explicitly differentiate from sibling tools like 'getCelestialDetails' or 'listCelestialObjects', which likely provide different astronomical data rather than navigation paths.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools or other contexts where star hopping might be preferred over direct object lookup. Usage is implied (e.g., for astronomical navigation when equipment FOV is limited), but no explicit when/when-not scenarios or prerequisites are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listCelestialObjectsB

Lists available celestial objects that can be queried by other tools. Objects are grouped by category. You can request all objects, or filter by a specific category. This tool helps in discovering what objects are known to the system.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNoOptional. Filters the list by category. Valid categories are: 'planets' (for Solar System objects like Sun, Moon, and planets), 'stars', 'messier' (for Messier objects), 'ic' (for Index Catalogue objects), 'ngc' (for New General Catalogue objects), 'dso' (for all Deep Sky Objects, including Messier, IC, NGC, and others), or 'all' (to list objects from all available categories). If omitted, defaults to 'all'.

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that objects are 'grouped by category' and can be filtered, but doesn't describe output format, pagination, rate limits, or error handling. For a tool with no annotations, this leaves significant gaps in understanding how the tool behaves beyond basic functionality.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences that efficiently convey purpose, functionality, and utility. It's front-loaded with the core action ('Lists available celestial objects') and avoids redundancy. However, the last sentence ('This tool helps in discovering...') could be considered slightly verbose, as it restates the purpose rather than adding new information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and filtering, but lacks details on output structure, error cases, or integration with siblings. Without annotations or output schema, more behavioral context would improve completeness for agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, fully documenting the single optional parameter 'category' with valid values and default behavior. The description adds minimal value beyond the schema, only implying filtering capability without providing additional syntax or format details. This meets the baseline score when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Lists available celestial objects that can be queried by other tools' and 'Objects are grouped by category.' It specifies the verb (lists) and resource (celestial objects) with additional context about grouping. However, it doesn't explicitly differentiate from sibling tools like getCelestialDetails or getStarHoppingPath, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating 'This tool helps in discovering what objects are known to the system' and mentions filtering by category, suggesting it's for discovery purposes. However, it lacks explicit guidance on when to use this tool versus alternatives like getCelestialDetails (which likely provides detailed info) or getStarHoppingPath (which might involve navigation). No exclusions or clear alternatives are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv1.0.0
    • First observedgetCelestialDetails
    • First observedgetStarHoppingPath
    • First observedlistCelestialObjects
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: getCelestialDetails retrieves detailed information for a specific object, getStarHoppingPath calculates navigation paths between objects, and listCelestialObjects provides a catalog for discovery. The descriptions clearly differentiate their functions, eliminating any ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in camelCase: getCelestialDetails, getStarHoppingPath, and listCelestialObjects. This uniformity makes the tools predictable and easy to understand, with no deviations in naming style.

Tool Count3/5

With only 3 tools, the server feels slightly thin for the celestial position domain, as it lacks operations like update or delete for observer settings or object data. However, the core functions (retrieve details, navigate, list objects) are covered, making it borderline but functional.

Completeness4/5

The tool set covers key aspects of celestial navigation: listing objects, getting details, and calculating paths. Minor gaps exist, such as no tools for configuring observer location or time, but agents can work around this by relying on pre-configured settings, and the core workflows are well-supported.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • chuk-mcp-celestial

    IBM
    A
    license
    A
    quality
    B
    maintenance
    Provides authoritative astronomical data including moon phases, solar eclipses, and sun/moon rise and set times using the US Navy API or offline Skyfield calculations. It enables users to query Earth's seasons and celestial events for any location and date.
    8
    1
    Apache 2.0

  • astronomy-oracle

    gregario
    A
    license
    A
    quality
    B
    maintenance
    Accurate astronomical catalog data and observing session planner for LLM assistants. Stops hallucinated magnitudes, coordinates, and visibility.
    3
    86
    3
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Rkm1999/CelestialMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server