Skip to content
Back to search

basilisk-mcp

Talk to Basilisk: an MCP server that lets Claude build, run and analyze Basilisk astrodynamics simulations, with one-click 3-D in Vizard.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/recepsuluker--basilisk-mcp/badge.svg)](/listings/recepsuluker--basilisk-mcp)

HTML

<a href="/listings/recepsuluker--basilisk-mcp"><img src="/api/listings/recepsuluker--basilisk-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 204 lines
  1. <p align="center">
  2. <img src="docs/images/hero.png" alt="basilisk-mcp: talk to Basilisk from Claude" width="100%">
  3. </p>
  4. <h1 align="center">basilisk-mcp</h1>
  5. <p align="center">
  6. <b>Talk to <a href="https://github.com/AVSLab/basilisk">Basilisk</a>.</b> Plan orbits and tune spacecraft attitude control
  7. in plain language, with real Basilisk simulations and 3-D playback in Vizard.
  8. </p>
  9. <p align="center">
  10. <a href="https://github.com/recepsuluker/basilisk-mcp/actions/workflows/ci.yml"><img src="https://github.com/recepsuluker/basilisk-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  11. <a href="LICENSE"><img src="https://img.shields.io/badge/license-ISC-blue.svg" alt="License: ISC"></a>
  12. <img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue" alt="Python 3.11–3.13">
  13. <img src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" alt="Windows, macOS, Linux">
  14. <img src="https://img.shields.io/badge/MCP-server-5598e7" alt="MCP server">
  15. </p>
  16. ---
  17. **basilisk-mcp** connects [Claude](https://claude.ai) (or any
  18. [Model Context Protocol](https://modelcontextprotocol.io) client) to **Basilisk**, the
  19. open-source astrodynamics framework from the University of Colorado Boulder. You
  20. describe a spacecraft problem; Claude builds the simulation, runs it with real
  21. Basilisk on your computer, analyzes the results, draws the plots and opens the run
  22. in 3-D.
  23. > *"Run the Basilisk reaction-wheel example, tune the gains so it settles faster, and show it in 3-D."*
  24. Claude answers with numbers you can check (settling time 418 s → 376 s, final error
  25. 0.138° → 0.002°), an explanation (the wheels saturate at 0.2 N·m), a comparison
  26. plot, Vizard open on your screen, and, if you ask, the exact Python script it ran.
  27. ## What you can ask
  28. | Ask Claude… | You get |
  29. |---|---|
  30. | *"Propagate a 700 km sun-synchronous orbit for three days with and without J2."* | orbit elements, RAAN drift vs. the analytic J2 rate, plots |
  31. | *"Run the reaction-wheel attitude example and tune it to settle under 6 minutes, wheels below 4000 rpm."* | gain sweep, settling times, wheel usage, comparison plot |
  32. | *"Build a 300 kg spacecraft in a 550 km orbit, nadir pointing with three HR12 wheels, starting from a tumble."* | a new scenario from scratch, validated before it runs |
  33. | *"Show it in Vizard."* | the run opens in Basilisk's 3-D visualizer |
  34. | *"Give me the script for that run."* | a standalone Basilisk Python script that reproduces it exactly |
  35. <p align="center">
  36. <img src="docs/images/j2_orbit_planes.png" width="48%" alt="J2 turns the orbit plane over ten days">
  37. <img src="docs/images/attitude_gains.png" width="48%" alt="Attitude error for three controller gain sets">
  38. </p>
  39. <p align="center"><sub>Both images come from runs made through basilisk-mcp. Left: J2 turns the orbit plane by
  40. −6.29°/day (analytic −6.27°/day). Right: three controller tunings of Basilisk's reaction-wheel example.</sub></p>
  41. ## Get started in 5 minutes
  42. You need **Python 3.11+**, **Git** and the **[Claude desktop app](https://claude.ai/download)**.
  43. Basilisk itself is installed automatically from PyPI (`bsk`); nothing has to be compiled.
  44. **1. Install**
  45. <details open>
  46. <summary><b>Windows (PowerShell)</b></summary>
  47. ```powershell
  48. winget install Python.Python.3.12 # skip if you already have Python 3.11+
  49. winget install Git.Git # skip if you already have Git; then reopen PowerShell
  50. cd $HOME
  51. git clone https://github.com/recepsuluker/basilisk-mcp.git
  52. cd basilisk-mcp
  53. py -3.12 -m venv .venv
  54. .venv\Scripts\python -m pip install -e ".[basilisk]"
  55. .venv\Scripts\basilisk-mcp doctor
  56. ```
  57. </details>
  58. <details>
  59. <summary><b>macOS / Linux</b></summary>
  60. ```bash
  61. git clone https://github.com/recepsuluker/basilisk-mcp.git
  62. cd basilisk-mcp
  63. python3 -m venv .venv
  64. .venv/bin/python -m pip install -e ".[basilisk]"
  65. .venv/bin/basilisk-mcp doctor
  66. ```
  67. </details>
  68. `doctor` checks that Basilisk imports and runs a short orbit simulation. Every line
  69. should say `[ok]`.
  70. **2. Connect it to Claude**
  71. ```powershell
  72. .venv\Scripts\basilisk-mcp install-claude --vizard-auto-open # macOS/Linux: .venv/bin/basilisk-mcp …
  73. ```
  74. This adds the server to Claude Desktop's configuration, keeps your other servers and
  75. settings, and saves a backup. Then **quit Claude completely** (tray or menu-bar icon
  76. → *Quit*) and start it again.
  77. **3. (Optional) Install Vizard for 3-D**
  78. Download [Vizard](https://avslab.github.io/basilisk/Vizard/VizardDownload.html) for your
  79. platform and unzip it into your home folder as `Vizard`. Check with
  80. `basilisk-mcp vizard --find`.
  81. **4. Ask**
  82. Open a new chat in Claude and try: *"List the Basilisk templates you can run."* You
  83. should see Claude call tools such as `list_templates` and `create_session`.
  84. Prefer Claude Code, a config file, or the HTTP transport? See
  85. [docs/connecting-claude.md](docs/connecting-claude.md).
  86. ## One-click scenarios
  87. Run a scenario and open it in Vizard without opening a chat:
  88. ```bash
  89. basilisk-mcp run attitude_feedback_rw # Basilisk's reaction-wheel example
  90. basilisk-mcp run basic_orbit --duration 86400 # one day of orbit propagation
  91. basilisk-mcp run s1a2b3c4d # a scenario you built with Claude
  92. ```
  93. ```
  94. Run r001 completed in 2.3 s (Basilisk 2.12.2)
  95. attitude error 82.06 deg -> 0.1378 deg (below 1 deg after 418 s)
  96. wheels peak speed 2917 rpm
  97. Opened Vizard: ...\runs\r001\vizard.bin
  98. ```
  99. Put these behind desktop shortcuts and each scenario is a double-click:
  100. [docs/one-click.md](docs/one-click.md).
  101. ## What's inside
  102. | | |
  103. |---|---|
  104. | **27 MCP tools** | create and edit scenarios, run, analyze (orbit, attitude, actuators), query, plot, compare, export CSV, export script, open in Vizard |
  105. | **Basilisk modules** | spacecraft hub · gravity (Earth, Moon, Mars, Sun, Venus, Jupiter; J2 for Earth and Mars) · reaction wheels (Honeywell HR12/14/16) · external torque · navigation · inertial and nadir pointing · tracking error · MRP feedback control · wheel torque mapping |
  106. | **Templates** | `basic_orbit`, `attitude_feedback_torque`, `attitude_feedback_rw` (mirroring the official Basilisk examples) and `nadir_pointing_rw` |
  107. | **Results** | settling time, final error, wheel speed vs. limit, orbit elements, J2 secular rates, energy drift, plots, CSV |
  108. | **3-D** | any run can record a Vizard file and open it with one call, command or click |
  109. Full references: [tools](docs/tools.md) · [modules and parameters](docs/modules.md) ·
  110. [Vizard](docs/vizard.md) · [configuration](docs/configuration.md).
  111. ## Why you can trust the numbers
  112. * **It is real Basilisk.** Each run is a generated, standalone Basilisk script executed
  113. by Basilisk itself. Ask for it with *"export the script"* and rerun it without the
  114. server.
  115. * **Checked against the official examples.** Tests reproduce
  116. `scenarioAttitudeFeedbackRW.py` (attitude error, wheel speeds, motor torques) and
  117. `scenarioBasicOrbit.py` (position and velocity) from the unmodified Basilisk
  118. examples, check J2 drift against analytic theory, and verify integrator accuracy.
  119. More than 100 tests run on Windows, macOS and Linux.
  120. * **Safe by design.** Claude can only assemble catalogued Basilisk modules with
  121. validated, unit-explicit parameters. No tool runs arbitrary code or touches files
  122. outside the server's data folder, and every run is an isolated, time- and
  123. memory-limited process. See [SECURITY.md](SECURITY.md).
  124. ## Troubleshooting
  125. | Problem | Fix |
  126. |---|---|
  127. | Claude doesn't use the basilisk tools | Run `basilisk-mcp install-claude` again, then quit Claude from the tray/menu-bar icon and restart it. Older chats may not see new tools: open a new chat. |
  128. | No *Developer* section in Claude's settings | Not needed: `install-claude` edits the configuration file for you. |
  129. | `doctor` says Basilisk can't be imported | Install it in the same environment: `pip install bsk`. |
  130. | Vizard doesn't open | `basilisk-mcp vizard --find`; unzip Vizard to your home folder as `Vizard`, or set `vizard_path` ([docs/vizard.md](docs/vizard.md)). |
  131. More in [docs/connecting-claude.md](docs/connecting-claude.md#8-troubleshooting).
  132. ## For developers
  133. * How the server is designed and how to build an MCP server like it:
  134. [docs/how-mcp-works.md](docs/how-mcp-works.md) and [PLAN.md](PLAN.md)
  135. * Contributing, adding Basilisk modules, regenerating reference data:
  136. [CONTRIBUTING.md](CONTRIBUTING.md)
  137. * Example results and the script that produces them: [examples/](examples/)
  138. ```bash
  139. pip install -e ".[dev]" && pytest
  140. ```
  141. ## Roadmap
  142. Atmospheric drag and orbit lifetime · thrusters and maneuvers (Δv, Hohmann) · SPICE
  143. ephemerides and third-body gravity · sensor noise models · eclipses and power ·
  144. ground-station access · Monte Carlo studies · live Vizard streaming. Ideas and pull
  145. requests are welcome.
  146. ## Acknowledgements
  147. [Basilisk](https://avslab.github.io/basilisk/) is developed by the Autonomous Vehicle
  148. Systems (AVS) Lab at the University of Colorado Boulder together with the Laboratory
  149. for Atmospheric and Space Physics (LASP), and is released under the ISC license. If you
  150. publish results obtained with Basilisk, please cite it as its documentation describes.
  151. The design of this server was informed by [GMAT-mcp](https://github.com/dcajacob/GMAT-mcp).
  152. basilisk-mcp is a community project and is not affiliated with or endorsed by the AVS
  153. Lab, LASP or Anthropic.
  154. ## License
  155. [ISC](LICENSE), the same license as Basilisk.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.