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

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 HTTP 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

• 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-<tag>-linux-x64
  • mcp-server-stdio-<tag>-win-x64.exe
  • mcp-server-stdio-<tag>-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

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:

• Markdown: docs/HowTo.md
• HTML (full): docs/howto.html
• HTML (compact): docs/howto-mini.html