brahe-mcp

<p align="center"> <a href="https://github.com/duncaneddy/brahe-mcp/actions/workflows/test.yml/badge.svg"> <img src="https://github.com/duncaneddy/brahe-mcp/actions/workflows/test.yml/badge.svg" alt="Tests"> </a> <a href="https://pypi.org/project/brahe-mcp/"> <img src="https://img.shields.io/pypi/v/brahe-mcp" alt="PyPI"> </a> </p>

This project provides a Model Context Protocol (MCP) server that exposes the astrodynamics capabilities of the Brahe library enabling language models to get smarter about astrodynamics and space situational awareness.

demo

Capabilities

Recent additions expose more of brahe's 1.7.0 astrodynamics surface as MCP tools:

Numerical propagation

propagate_numerical supports non-Earth central bodies via the body-specific force model presets (lunar_default, mars_default, cislunar_default), or by setting force_model="central_body" with central_body set to moon, mars, or emb; the bci/bcbf output frames report state relative to that body. (central_body is only consulted for the central_body preset — other presets bake in their own body.) Two optional structured config dicts also replace the previous per-force keyword arguments:

• force_config: {gravity, drag, srp, third_body, tides, relativity, frame_transform}
• integrator: {preset, method, abs_tol, rel_tol, initial_step, max_step, store_accelerations}

Call list_propagation_options() to discover the valid keys and values for both dicts.

Mean and osculating elements

convert_mean_osculating handles a single state using the Brouwer-Lyddane analytical theory. convert_mean_osculating_batch handles a time series and additionally supports the numerical windowed-averaging method.

Two things to know about the numerical method:

• It is batch-only. The single-state tool rejects it.
• With edge="truncate" (the default), osculating-to-mean returns **fewer

states than it receives**, because the averaging window consumes the edges of the series. Read n_output and dropped_by_edge_handling from the response rather than assuming the length is preserved.

Numerical mean-to-osculating inverts the averaging by differential correction and therefore requires a force_config; call list_propagation_options() for the valid keys. Brouwer-Lyddane is a first-order theory, so mean-to-osculating followed by osculating-to-mean does not return the input exactly.

Plotting output

Plotting depends on the brahe[plots] extra, which is installed automatically as a dependency of brahe-mcp. The 3D plot tools also write an interactive HTML file to disk; the directory is configurable via the BRAHE_MCP_OUTPUT_DIR environment variable (default <tempdir>/brahe-mcp-plots).

Installation

uv tool install brahe-mcp

or

pip install brahe-mcp

Then configure your MCP client to use the installed tool:

{
  "mcpServers": {
    "brahe": {
      "command": "brahe-mcp"
    }
  }
}

The MCP configuration location depends on your client. For popular tools you can find it here:

[!NOTE] ChatGPT Desktop does not support local stdio MCP servers — it requires remote HTTPS endpoints

OpenAI Codex CLI

Codex CLI stores MCP configuration in TOML format at ~/.codex/config.toml (or project-scoped .codex/config.toml):

[mcp_servers.brahe]
command = "brahe-mcp"
args = []

You can also add it via the CLI:

codex mcp add brahe -- brahe-mcp

To include SpaceTrack credentials:

codex mcp add brahe --env [email protected] --env SPACETRACK_PASS=your-password -- brahe-mcp

SpaceTrack Configuration

The SpaceTrack tools require a Space-Track.org account. Add your credentials via the env key in the server config:

{
  "mcpServers": {
    "brahe": {
      "command": "brahe-mcp",
      "env": {
        "SPACETRACK_USER": "[email protected]",
        "SPACETRACK_PASS": "your-password"
      }
    }
  }
}

[!NOTE] Claude Desktop does not expand shell variables like ${SPACETRACK_USER} — you must put the actual values in the config. Claude Code inherits your shell environment, so you can alternatively set the variables in ~/.zshrc and omit the env block.

Without these variables, the CelesTrak tools will still work normally — only the SpaceTrack tools will return an error prompting you to set the credentials.

Local Setup

To run the server from a local clone (useful for development or testing before installing):

git clone https://github.com/duncaneddy/brahe-mcp.git
cd brahe-mcp
uv sync --group dev

Then configure your MCP client to launch the server via uv run. Add the following to your MCP settings file:

{
  "mcpServers": {
    "brahe": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/brahe-mcp", "brahe-mcp"]
    }
  }
}

Replace /path/to/brahe-mcp with the absolute path to your local clone.

Development

uv sync --group dev
uv run pytest tests/