🌌 Stellarium MCP Server

A high-performance Model Context Protocol (MCP) server implemented in Rust. This server bridges standard Large Language Models (LLMs) with Stellarium, the world's most popular open-source planetarium, via its Remote Control Plugin.

[!IMPORTANT] This server allows an LLM to control Stellarium's simulation time, camera, and location, as well as retrieve deep-sky object data and SIMBAD lookups.

🏗️ Architecture

The server acts as a JSON-RPC gateway over standard IO (stdio).

graph LR
    A[LLM Client] <-->|JSON-RPC / stdio| B[stellarmcp Server]
    B <-->|HTTP REST / RemoteControl| C[Stellarium App]

• Runtime: Built with tokio for asynchronous I/O.
• Protocol: Fully compliant with the Model Context Protocol (v2024-11-05).
• Backend interface: Communicates with Stellarium's RemoteControl plugin (default port 8090).

🛠️ Installation & Building

Prerequisites

1. Rust: Install the latest stable toolchain via rustup.rs.
2. Stellarium: Download and run Stellarium.
3. Plugin Configuration:
   • Open Stellarium.
   • Go to Configuration (F2) -> Plugins.
   • Select Remote Control.
   • Check Load at startup.
   • Click configure, ensure Server enabled is checked and the port is 8090.
   • Restart Stellarium.

Build

Clone this repository and build the release binary:

cargo build --release

The executable will be located at:
./target/release/stellarmcp.exe

🚀 Usage

Configuring your LLM Client

Add the following to your MCP configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "stellarium": {
      "command": "C:\\path\\to\\stellarmcp.exe",
      "env": {
        "STELLARIUM_URL": "http://localhost:8090"
      }
    }
  }
}

🧰 Available Tools

| Tool | Description | | :--- | :--- | | stellarium_get_status | Get current time, location, view, and selected object. | | stellarium_set_location | Change observer location (Latitude, Longitude). | | stellarium_set_time | Set simulation Julian Day and time rate. | | stellarium_find_object | Search for objects in Stellarium's internal catalogs. | | stellarium_object_info | Get detailed JSON metadata for a specific astronomical object. | | stellarium_focus | Center the view on a target name or J2000 coordinate. | | stellarium_move | Pan the viewport (altitude/azimuth speed). | | stellarium_set_fov | Set the Field of View (zoom level). | | stellarium_simbad_lookup | Query the SIMBAD online database for object data. | | stellarium_run_script | Execute raw Stellarium API JavaScript directly. |

🧪 Testing

The project includes a robust test suite using mockito for API mocking.

cargo test --all

📜 License

MIT

🌌 Clear Skies!