IO Aerospace MCP Server

Use it now

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

Transport Protocols:

Streamable-HTTP (recommended): https://mcp.io-aerospace.org/ - Modern MCP transport protocol

SSE (legacy): https://mcp.io-aerospace.org/sse - For backward compatibility with older MCP clients only

Note: Use the base URL with modern MCP clients - they will automatically use the streamable-HTTP transport. Only use the /sse endpoint if you have an older client that specifically requires SSE protocol.

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 local MCP clients)
HTTP Transport: Supports both modern streamable-HTTP and legacy SSE protocols for web-based integrations
- Streamable-HTTP (default, recommended): Modern MCP protocol at the base URL
- SSE (legacy): Available at /sse endpoint for backward compatibility only

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.

Repository: https://github.com/IO-Aerospace-software-engineering/Astrodynamics

Use the hosted server (recommended)

You can start integrating immediately against the production instance:

Base URL (streamable-HTTP): https://mcp.io-aerospace.org/ - Use this with modern MCP clients
SSE endpoint (legacy): https://mcp.io-aerospace.org/sse - Only for older clients requiring SSE protocol

Important: Modern MCP clients (2024+) should use the base URL with streamable-HTTP transport. The SSE endpoint is maintained only for backward compatibility with older implementations.

Example (legacy SSE - browser/Node):

// Only use this if you have an old client that requires SSE
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.Http/                 # HTTP transport server (streamable-HTTP + legacy SSE)
├── 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

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 HTTP server will be available at http://localhost:8080.

Production

Copy docker-compose.prod.example.yml to docker-compose.prod.yml
Update the domain names in the production file
Ensure kernel data exists at ./data/solarsystem/
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

HTTP 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

HTTP Transport (For Web/HTTP)

cd Server.Http
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:

```json
{
  "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 by specifying the base URL only. Modern MCP clients will use streamable-HTTP:

{
  "mcpServers": {
    "astrodynamics": {
      "transport": {
        "type": "http",
        "url": "https://mcp.io-aerospace.org"
      }
    }
  }
}

The base URL uses the modern streamable-HTTP transport protocol
Do NOT append /sse - that's only for legacy SSE clients
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 (streamable-HTTP)

Using the MCP SDK to connect to the hosted server with modern streamable-HTTP transport:

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

// Modern streamable-HTTP transport (recommended)
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.

Sponsor page: https://github.com/sponsors/IO-Aerospace-software-engineering
Businesses: open an issue to discuss invoices or custom arrangements

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

Troubleshooting

Common Issues

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

Log Monitoring

# Development
docker-compose logs -f

# Production
docker logs -f container-name

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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:

Markdown: docs/HowTo.md

HTML (full): docs/howto.html

HTML (compact): docs/howto-mini.html

mcp-server

Documentation