パッケージの詳細

celestial-position-mcp

rkm199939ISC1.0.2

MCP server for celestial object altitude-azimuth coordinates

mcp, astronomy, celestial, coordinates

readme

Celestial Position MCP Server

An MCP (Model Context Protocol) server that provides altitude-azimuth coordinates for celestial objects using the current system time and a configured location.

Features

  • Get altitude and azimuth coordinates for various celestial objects
  • Uses system time by default (with option to specify custom time)
  • Uses configurable location settings
  • Supports a wide range of celestial objects:
    • Solar system objects (Sun, Moon, planets)
    • Over 117,000 stars from the HYG Database
    • Over 14,000 deep sky objects from the OpenNGC catalog
    • Includes Messier, NGC, and IC objects
  • Raw coordinates without atmospheric refraction correction
  • Fast lookup with efficient database management

Installation

Option 1: From npm

npm install -g celestial-position-mcp

This will install the package globally so you can run it as a command:

celestial-position-mcp

Or install it locally in your project:

npm install celestial-position-mcp

Option 2: From GitHub

  1. Make sure you have Node.js and npm installed
  2. Clone this repository
  3. Install dependencies:
    npm install
  4. Build the project:
    npm run build
  5. Start the server:
    npm start

Catalog Setup

The server exclusively uses astronomical catalogs from the /data directory. The catalog loading process follows this order:

  1. Use downloaded catalogs from /data directory:

    npm run fetch-catalogs

    This downloads catalog files directly to the data directory:

    • ngc.csv - OpenNGC Catalog (14,069 objects)
    • hygdata_v41.csv - HYG Database v41 (117,949 stars)

  2. Automatic download: If no catalogs are found when starting the server, it will attempt to download them automatically.

  3. Fallback catalogs: If download fails, the server falls back to sample catalogs or hardcoded data.

Configuration

Before using the server, update your location in src/config.ts:

export const OBSERVER_CONFIG = {
  latitude: 49.2827, // Vancouver latitude (replace with your latitude)
  longitude: -123.1207, // Vancouver longitude (replace with your longitude)
  altitude: 30, // Elevation in meters
  temperature: 15, // Default temperature in Celsius
  pressure: 1013.25 // Default pressure in hPa
};

export const SERVER_CONFIG = {
  port: 3005, // The server port
  host: 'localhost'
};

Usage

  1. Build the project:

    npm run build

  2. Start the server:

    npm start

  3. The server will start at http://localhost:3005/mcp

  4. Use the included test page at test.html to try out the APIs

Testing

Open test.html in your browser to access a simple interface for testing the server's functionality. You can:

  • Look up the position of any celestial object
  • List available objects by category
  • Test with custom date/time settings

Available Tools

getCelestialPosition

Gets altitude and azimuth coordinates for a celestial object.

Parameters:

  • objectName (required): Name of the celestial object (e.g., "Jupiter", "Sirius", "M31")
  • useSystemTime (optional, default: true): Whether to use the current system time
  • dateTime (optional): Custom observation time in ISO format (only used if useSystemTime is false)
    • Use format like "2025-04-15T21:30:00Z" for UTC time
    • Use format like "2025-04-15T21:30:00" for local time (system timezone)

listCelestialObjects

Lists available celestial objects by category.

Parameters:

  • category (optional, default: "all"): Filter by category ("planets", "stars", "dso", "all")

Using with Claude

Manual Connection

  1. Start the server using npm start or npm run dev
  2. Enable developer mode in Claude Desktop
  3. Add your MCP server: http://localhost:3005/mcp
  4. Ask Claude to get celestial positions

Auto-Start Configuration

To have Claude automatically start the celestial position server:

If installed via npm (globally)

Add the following to your Claude MCP configuration (usually in %APPDATA%/Claude/claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on MacOS):

mcp_config = {
  "mcpServers": {
    // Your other servers here...

    "celestial-position": {
      "command": "npx",
      "args": [
        "-y",
        "celestial-position-mcp"
      ]
    }
  }
}

If installed from GitHub

  1. Build the project first:

    npm run build

  2. Add the following to your Claude MCP configuration:

    mcp_config = {
  "mcpServers": {
    // Your other servers here...

    "celestial-position": {
      "command": "node",
      "args": [
        "C:\\Users\\ryu\\mcp_local\\celestialPosition\\dist\\index.js"
      ]
    }
  }
}

  3. Adjust the path in the args array to match the actual location of your project

Now you can ask Claude questions like:

  • "Where is Jupiter in the sky right now?"
  • "What's the position of Sirius?"
  • "Can I see M31 from my location tonight?"

Adding to Existing MCP Configuration

If you already have an MCP configuration with other servers, simply add the celestial-position entry to your existing configuration:

mcp_config = {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "C:\\Users\\ryu\\Downloads",
          "C:\\Users\\ryu\\Desktop",
          "C:\\Users\\ryu\\mcp_local"
        ]
      },
      "brave-search": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-brave-search"
        ],
        "env": {
          "BRAVE_API_KEY": "YOUR_API_KEY"
        }
      },
      // Add the celestial-position server here:
      "celestial-position": {
        "command": "node",
        "args": [
          "C:\\Users\\ryu\\mcp_local\\celestialPosition\\dist\\index.js"
        ]
      }
    }
}

This will allow Claude to start multiple MCP servers, including your celestial position server.

Development

To run in development mode with automatic reloading:

npm run dev

Project Structure

  • src/index.ts - Entry point
  • src/server.ts - MCP server implementation
  • src/config.ts - Location and server configuration
  • src/fetch-catalogs.ts - Script to download catalog files
  • src/utils/astronomy.ts - Star and DSO catalog handling and coordinate calculations
  • src/tools/ - Tool implementations (getCelestialPosition, listCelestialObjects)
  • data/ - Astronomical catalog files

Resources

License

ISC