Skip to content

IO-Aerospace-software-engineering/mcp-server

BranchesTags

Repository files navigation

IO Aerospace MCP Server

Use it now

Hosted in production (no setup needed): https://mcp.io-aerospace.org/

SSE endpoint: https://mcp.io-aerospace.org/sse

Note: Most MCP clients that support HTTP/SSE only need the base URL; they will connect to the SSE stream internally (commonly at /sse). The explicit /sse URL is provided here for manual/web integrations.

A Model Context Protocol (MCP) server for aerospace and astrodynamics calculations, providing tools for celestial body ephemeris, orbital mechanics, and space mission analysis.

Overview

This MCP server provides two transport options:

  • STDIO Transport: Standard input/output communication (recommended for MCP clients)
  • SSE Transport: HTTP Server-Sent Events for web-based integrations

The server includes comprehensive tools for:

  • Celestial body ephemeris and state vector calculations
  • Orbital mechanics and geometry computations
  • Deep Space Network (DSN) ground station operations
  • Solar system object properties and characteristics
  • Mathematical conversions for aerospace calculations
  • Time system conversions and utilities

Astrodynamics Framework

This server is powered by the IO Aerospace Astrodynamics framework, which provides the core algorithms for ephemerides, orbital mechanics, geometry, and time systems.

Use the hosted server (recommended)

You can start integrating immediately against the production instance:

Example (browser/Node):

const eventSource = new EventSource('https://mcp.io-aerospace.org/sse');

eventSource.onmessage = (event) => {
  console.log('message', event.data);
};

eventSource.onerror = (err) => {
  console.error('sse error', err);
};

Self-hosting is optional; see below for Docker and .NET instructions.

Project Structure

mcp-server/
├── AI/                           # AI tools and models
│   ├── Tools/                    # Core calculation tools
│   ├── Models/                   # Data models and types
│   └── Converters/              # Type converters
├── Data/                         # Data providers and solar system kernels
│   ├── SolarSystem/             # SPICE kernel files
│   └── SolarSystemObjects/      # Celestial body definitions
├── Server.Sse/                  # HTTP/SSE transport server
├── Server.Stdio/                # STDIO transport server
├── docker-compose.yml           # Development Docker configuration
├── docker-compose.prod.example.yml  # Production template
└── deploy-production.sh         # Production deployment script

Prerequisites

  • .NET 9.0 SDK or runtime
  • Docker (for containerized deployment)
  • Solar system kernels data (SPICE kernels)

Available Tools

CelestialBodyTools

  • GetEphemerisAsStateVectors: Calculate state vectors (position and velocity) of celestial bodies
  • GetCelestialBodyProperties: Retrieve geophysical properties of planets and moons

OrbitalParametersTools

  • ConvertStateVectorToKeplerianElements: Convert state vectors to Keplerian orbital elements
  • ConvertStateVectorToEquinoctialElements: Convert state vectors to equinoctial elements
  • ConvertStateVectorToEquatorialCoordinates: Convert state vectors to equatorial coordinates
  • ConvertKeplerianElementsToStateVector: Convert Keplerian elements back to state vectors
  • ConvertEquinoctialElementsToStateVector: Convert equinoctial elements back to state vectors
  • ConvertStateVectorToTheGivenFrame: Transform state vectors between reference frames

GeometryFinderTools

  • FindCoordinateConstraint: Find time windows when coordinate constraints are met
  • FindDistanceConstraint: Find time windows when distance constraints are satisfied
  • FindOccultingConstraint: Find occultation and eclipse events

SiteTools

  • GetDeepSpaceStationPlanetodeticCoordinates: Get latitude, longitude, and altitude of DSS stations
  • GetDeepSpaceStationStateVector: Calculate state vectors for ground stations
  • GetHorizontalCoordinates: Get azimuth and elevation from ground stations
  • GetDSSFrame: Retrieve reference frame information for DSS stations

TimeTools

  • ConvertDateTime: Convert between different time systems (UTC, TDB, TAI, TDT, GPS)
  • CurrentDateTime: Get current UTC date and time

MathTools

  • DegreesToRadians / RadiansToDegrees: Angular unit conversions
  • ConvertDegreesToHours / ConvertHoursToDegrees: Time-angle conversions
  • DegreesToArcseconds / ArcsecondsToDegrees: Angular precision conversions
  • RadiansToArcseconds / ArcsecondsToRadians: Angular unit conversions
  • MetersToMiles / MilesToMeters: Distance unit conversions
  • MetersToFeet / FeetToMeters: Distance unit conversions
  • MetersToKilometers / KilometersToMeters: Metric distance conversions
  • MetersToAstronomicalUnits / AstronomicalUnitsToMeters: Astronomical distance conversions
  • MetersToParsec / ParsecToMeters: Stellar distance conversions
  • MetersToLightYears / LightYearsToMeters: Cosmic distance conversions

Quick Start (self-hosting)

Docker Deployment

Development

git clone https://github.com/IO-Aerospace-software-engineering/mcp-server
cd mcp-server
docker-compose up

The SSE server will be available at http://localhost:8080.

Production

  1. Copy docker-compose.prod.example.yml to docker-compose.prod.yml
  2. Update the domain names in the production file
  3. Ensure kernel data exists at ./data/solarsystem/
  4. Deploy using the automated script:
./deploy-production.sh

Native .NET Deployment

1. Clone and Build

git clone https://github.com/IO-Aerospace-software-engineering/mcp-server
cd mcp-server
dotnet build

2. Solar System Data Setup

The server requires SPICE kernels for solar system calculations.

  • STDIO server configuration (no appsettings):
    • Provide the kernels path via CLI or environment variable
    • Priority: CLI flag > IO_DATA_DIR environment variable
    • CLI flags: -k <path>, --kernels <path>, or --kernels-path <path>

Examples:

# Using CLI flag
./Server.Stdio -k /path/to/your/spice/kernels

# Using environment variable (Linux/macOS)
export IO_DATA_DIR="/path/to/your/spice/kernels"
./Server.Stdio

# Windows (PowerShell)
$env:IO_DATA_DIR="C:\path\to\your\spice\kernels"
./Server.Stdio.exe
  • SSE server configuration: may use appsettings.json as before.

Required Kernel Files:

kernels/
├── de440s.bsp              # Planetary ephemeris
├── latest_leapseconds.tls  # Leap seconds
├── pck00011.tpc           # Planetary constants
├── earth_latest_high_prec.bpc  # Earth orientation
└── ...                    # Additional kernel files

3. Choose Transport Method

STDIO Transport (For MCP Clients)
  • Release assets are native executables per OS/RID (no ZIP). Filenames:
    • mcp-server-stdio--linux-x64
    • mcp-server-stdio--win-x64.exe
    • mcp-server-stdio--osx-arm64
  • On macOS, a sidecar native library may be provided (e.g., libIO.Astrodynamics.so). Place it in the same directory as the executable.
# After publishing or downloading a release asset for your OS
./Server.Stdio -k /path/to/kernels
SSE Transport (For Web/HTTP)
cd Server.Sse
dotnet run
# Server available at http://localhost:8080

Docker Configuration

Development Environment

  • File: docker-compose.yml
  • Ports: 8080 (HTTP), 8081 (HTTPS)
  • Data: Mounted from ./Data/SolarSystem
  • Usage: docker-compose up

Production Environment

  • File: docker-compose.prod.yml (create from example)
  • Features: Traefik reverse proxy, optimized images
  • Data: Host-mounted from ./data/solarsystem
  • Deployment: Automated via deploy-production.sh

MCP Client Integration

Note: Many MCP clients use JSON-based configuration files, but schemas differ per client. The JSON examples below use Claude Desktop’s schema; adapt keys to your client’s format.

Claude Desktop Configuration (STDIO)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "astrodynamics": {
      "command": "/path/to/Server.Stdio",
      "args": ["-k", "/path/to/kernels"]
    }
  }
}

Alternatively, set an environment variable if your client supports it:

{
  "mcpServers": {
    "astrodynamics": {
      "command": "/path/to/Server.Stdio",
      "args": [],
      "env": {
        "IO_DATA_DIR": "/path/to/kernels"
      }
    }
  }
}

Claude Desktop Configuration (HTTP transport to hosted server)

Use your production server over HTTP/SSE by specifying the base URL only:

{
  "mcpServers": {
    "astrodynamics": {
      "transport": {
        "type": "http",
        "url": "https://mcp.io-aerospace.org"
      }
    }
  }
}
  • Only the base URL is required; the client will use the SSE stream internally (commonly at /sse).
  • This schema is for Claude Desktop; other clients may use different keys.

Other MCP clients

  • Provide the base URL: https://mcp.io-aerospace.org
  • Add headers (e.g., Authorization) only if your deployment requires it
  • Don’t append /sse unless your client documentation requires it; most discover the SSE path
  • Refer to your client’s documentation for the exact JSON schema or settings UI

Node.js MCP client (HTTP/SSE)

Using the MCP SDK to connect to the hosted server and list tools:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { HttpClientTransport } from "@modelcontextprotocol/sdk/client/transport/http.js";

const transport = new HttpClientTransport(new URL("https://mcp.io-aerospace.org"));
const client = new Client(
  { name: "example-client", version: "1.0.0" },
  { capabilities: { tools: {}, prompts: {}, resources: {} } },
  transport
);

await client.connect();
const tools = await client.listTools();
console.log("Tools:", tools);

// Example: call a tool
// const result = await client.callTool({ name: "GetEphemerisAsStateVectors", arguments: { /* ... */ } });
// console.log(result);

Sponsor

If this project helps your work, please consider sponsoring ongoing development, hosting, and data updates.

Your support helps keep the hosted server online and the SPICE data current.

Troubleshooting

Common Issues

  1. "Kernels directory does not exist": Verify the path passed with -k (or IO_DATA_DIR) exists and contains SPICE files
  2. "Failed to load kernel": Ensure all required kernel files are present and accessible
  3. Connection errors: Check firewall settings and port availability

Log Monitoring

# Development
docker-compose logs -f

# Production
docker logs -f container-name

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

  • Create an issue on GitHub
  • Check the troubleshooting section above
  • Review the deployment guide in DEPLOYMENT_GUIDE.md

Sylvain

New: A step-by-step How To guide is available:

About

An aerospace server who implements model context protocol

Resources

Readme

License

AGPL-3.0 license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases 1

v0.1.4 Latest
Aug 24, 2025

Sponsor this project

 
Learn more about GitHub Sponsors

Packages

No packages published

Languages