IO Aerospace

You can run the IO Aerospace MCP Server to perform celestial mechanics, ephemeris calculations, and mission analysis against either a hosted production instance or a self-hosted setup. It provides both modern streamable-HTTP transport for web integrations and a STDIO transport for local clients, along with a robust set of tools for orbital dynamics, time systems, geometry, and ground station operations.

How to use

Connect to a MCP client using the hosted, production instance for immediate work against planetary ephemeris, orbital mechanics, and time-conversion tools. Use the base URL with modern MCP clients to automatically employ the streamable-HTTP transport. If you have an older client that requires the SSE protocol, connect to the dedicated SSE endpoint at the /sse path.

Two transport options are available: the modern streamable-HTTP API at the base URL and a legacy SSE endpoint for backward compatibility. For local testing or containerized deployments, you can run a STDIO server locally or start an HTTP server that serves the same MCP capabilities.

How to install

Prerequisites you need before starting include the .NET 9.0 SDK or runtime and Docker for containerized deployment. You also need solar system kernel data (SPICE kernels) for accurate ephemeris and geometry computations.

Self-hosting can be done via Docker or native .NET deployment. The following steps guide you through both options. After installation, you can choose either the STDIO transport for local MCP clients or the HTTP transport for web-based usage.

Configuration and startup notes

Self-hosted, STDIO mode requires supplying the SPICE kernels path either via a CLI flag or an environment variable. The priority is CLI flags over environment variables. Use the -k flag or --kernels to specify the kernels directory.

Self-hosted, HTTP mode runs the HTTP server from the Server.Http project and serves requests via the base URL. The hosted production instance uses the base URL https://mcp.io-aerospace.org for streamable-HTTP and https://mcp.io-aerospace.org/sse for legacy SSE.

A minimal production start and a local test start follow the commands shown below. The production deployment uses the provided scripts and compose files to ensure a proper runtime with data mounted from the solarsystem kernels.

Additional sections

Security and access considerations: When running self-hosted, consider applying network restrictions around the HTTP endpoint, and ensure your environment variables or CLI flags do not expose sensitive kernel data paths. If you expose the API to the internet, monitor access and apply appropriate authentication as needed for your deployment.

Troubleshooting tips: If kernels cannot be found or loaded, verify that the kernels directory exists and that all required kernel files are present and accessible. Check container logs or local process logs for hints about missing data or permission issues.

Notes on client integration: Many MCP clients use JSON-based configuration files with varying schemas. You should adapt the connection configuration to match your client’s expected format, using the base URL for the hosted HTTP transport or the local STDIO command for a local server.

Available tools

GetEphemerisAsStateVectors

Calculate state vectors (position and velocity) of celestial bodies using ephemeris data.

GetCelestialBodyProperties

Retrieve geophysical properties of planets and moons.

ConvertStateVectorToKeplerianElements

Convert a state vector into Keplerian orbital elements.

ConvertStateVectorToEquinoctialElements

Convert a state vector into equinoctial orbital elements.

ConvertStateVectorToEquatorialCoordinates

Convert a state vector to right ascension and declination coordinates.

ConvertKeplerianElementsToStateVector

Convert Keplerian elements back into a state vector.

FindCoordinateConstraint

Find time windows where coordinate constraints are satisfied.

FindDistanceConstraint

Find time windows where distance constraints are met.

FindOccultingConstraint

Detect occultation and eclipse events between bodies.

GetDeepSpaceStationPlanetodeticCoordinates

Get geodetic coordinates for ground station points.

GetDeepSpaceStationStateVector

Calculate state vectors for Deep Space Network stations.

GetHorizontalCoordinates

Compute azimuth and elevation for a ground-based observer.

ConvertDateTime

Convert between different time systems, such as UTC, TDB, TAI, GPS.

CurrentDateTime

Get the current UTC date and time.

DegreesToRadians

Convert angles from degrees to radians.

RadiansToDegrees

Convert angles from radians to degrees.

MetersToKilometers

Convert distance from meters to kilometers.

KilometersToMeters

Convert distance from kilometers to meters.