Content
# STK-MCP
[](https://www.python.org/downloads/) [](https://pypi.org/project/mcp/)
STK-MCP is an MCP (Model Context Protocol) server designed to enable Large Language Models (LLMs) or other MCP clients to interact with [Ansys/AGI STK](https://www.ansys.com/products/missions/ansys-stk) (Systems Tool Kit) - the leading Digital Mission Engineering software.
This project allows controlling STK via an MCP server, supporting both STK Desktop (Windows only) and STK Engine (Windows & Linux). It utilizes `FastMCP` from the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
## Overview
The primary goal of this project is to bridge the gap between programmatic interaction and the powerful simulation capabilities of STK. By exposing STK functionalities through a robust CLI and an MCP server, users can command STK simulations using simple commands or LLM-driven applications.
The MCP application, defined in `src/stk_mcp/app.py`, exposes STK operations as MCP tools, which are dynamically managed by a CLI entry point in `src/stk_mcp/cli.py`.
## Features
* CLI entry point powered by `Typer`.
* Dual mode operation: STK Engine (Windows/Linux) and STK Desktop (Windows).
* OS-aware: Desktop mode auto-disabled on non-Windows platforms.
* Managed lifecycle: STK instance is started/stopped with the MCP server.
* Tool discovery: `list-tools` command enumerates available MCP tools.
* Modular architecture: CLI (`cli.py`), MCP (`app.py`), STK logic (`stk_logic/`), and MCP tools (`tools/`).
## Prerequisites
* **Operating System:** Windows or Linux. STK Desktop mode requires Windows.
* **Python:** Version 3.12 or higher.
* **Ansys/AGI STK:** Version 12.x Desktop or Engine installed.
* **STK Python API:** The `agi.stk12` Python wheel corresponding to your STK installation must be available. Typically found under `CodeSamples\Automation\Python` in your STK install.
## Installation
1. Clone the repository
```bash
git clone <repository-url>
cd stk-mcp
```
2. Create and activate a virtual environment
```bash
# Create the virtual environment
uv venv
# Activate it
# On Windows (in PowerShell/CMD):
# .venv\Scripts\activate
# On Linux (in bash/zsh):
source .venv/bin/activate
```
3. Add dependencies with uv (preferred)
- Add the STK Python wheel from your STK installation (local file):
```bash
uv add ./agi.stk12-12.10.0-py3-none-any.whl
# or: uv add path/to/your/STK/CodeSamples/Automation/Python/agi.stk12-*.whl
```
4. Sync the environment (installs deps from `pyproject.toml`)
```bash
uv sync
```
## Usage
This project is a command-line application. Ensure your virtual environment is activated before running commands.
### Listing Available Tools
```bash
uv run -m stk_mcp.cli list-tools
```
Prints a table of tool names and their descriptions.
### Running the MCP Server
Use the `run` command to start the MCP server. The server will automatically start and manage an STK instance.
Run with `uv run` so you don’t need to install the package into site-packages.
**1) STK Engine (recommended for automation, Windows/Linux):**
```bash
uv run -m stk_mcp.cli run --mode engine
```
**2) STK Desktop (Windows only, shows GUI):**
Ensure STK Desktop is closed; the server will launch and manage its own instance.
```bash
uv run -m stk_mcp.cli run --mode desktop
```
The server will start, initialize STK, and listen for MCP connections on `http://127.0.0.1:8765` by default.
**3. Command Options:**
You can see all options with the `--help` flag:
```bash
stk-mcp run --help
```
### Interacting with the Server
Once the server is running, you can connect to it using any MCP client, such as the MCP Inspector.
1. Open the MCP Inspector URL provided in the console (e.g., `http://127.0.0.1:8765`).
2. Find the "STK Control" server in the list.
3. Use the "Tools" section to execute `setup_scenario`, `create_location`, and `create_satellite`.
### Stopping the Server
Press `Ctrl+C` in the terminal where the server is running. The lifecycle manager will automatically close the STK Engine or Desktop instance.
## MCP Tools and Resources
The server exposes the following MCP tools/resources.
| Name | Kind | Description | Desktop (Windows) | Engine (Windows) | Engine (Linux) |
|------------------|----------|-----------------------------------------------------------------------------------------------|-------------------|------------------|----------------|
| `setup_scenario` | Tool | Create/configure an STK Scenario; sets time period and rewinds animation. | Yes | Yes | Yes |
| `create_location`| Tool | Create/update a `Facility` (default) or `Place` at latitude/longitude/altitude (km). | Yes | Yes | Yes |
| `create_satellite`| Tool | Create/configure a satellite from apogee/perigee (km), RAAN, and inclination; TwoBody prop. | Yes | Yes | No |
Resources:
| Name | Kind | Description | Desktop (Windows) | Engine (Windows) | Engine (Linux) |
|------|------|-------------|-------------------|------------------|----------------|
| `resource://stk/objects` | Resource | List all objects in the active scenario. Returns JSON records: `{name, type}`. | Yes | Yes | Yes |
| `resource://stk/objects/{type}` | Resource | List objects filtered by `type` (e.g., `satellite`, `facility`, `place`, `sensor`). Returns JSON records. | Yes | Yes | Yes |
| `resource://stk/health` | Resource | Report basic state: mode, scenario name, and object counts. | Yes | Yes | Yes |
| `resource://stk/analysis/access/{object1}/{object2}` | Resource | Compute access intervals between two objects. Provide paths like `Satellite/SatA` and `Facility/FacB` (with or without leading `*/`). | Yes | Yes | Yes |
| `resource://stk/reports/lla/{satellite}` | Resource | Return satellite LLA ephemeris over the scenario start/stop interval. Provide path like `Satellite/SatA` (with or without leading `*/`). | Yes | Yes | Yes |
Examples:
- Read all objects: `resource://stk/objects`
- Read only satellites: `resource://stk/objects/satellite`
- Read ground locations: `resource://stk/objects/location` (alias for facilities and places)
Access and LLA examples:
- Compute access: `resource://stk/analysis/access/Satellite/ISS/Facility/Boulder`
- Get ISS LLA (60 s): `resource://stk/reports/lla/Satellite/ISS` (optional `step_sec` argument)
## Configuration & Logging
Configuration is centralized in `src/stk_mcp/stk_logic/config.py` using `pydantic-settings`.
Defaults can be overridden with environment variables (prefix `STK_MCP_`).
- `STK_MCP_DEFAULT_HOST` (default `127.0.0.1`)
- `STK_MCP_DEFAULT_PORT` (default `8765`)
- `STK_MCP_LOG_LEVEL` (default `INFO`)
- `STK_MCP_DEFAULT_SCENARIO_NAME` (default `MCP_STK_Scenario`)
- `STK_MCP_DEFAULT_START_TIME` (default `20 Jan 2020 17:00:00.000`)
- `STK_MCP_DEFAULT_DURATION_HOURS` (default `48.0`)
Logging is standardized via `src/stk_mcp/stk_logic/logging_config.py`. The CLI uses
this configuration, producing structured logs with timestamps, levels, and context.
## Implementation Notes
- STK access is serialized with a global lock to avoid concurrency issues.
- Common STK-availability checks are handled via decorators in
`src/stk_mcp/stk_logic/decorators.py` (`@require_stk_tool` and `@require_stk_resource`).
- STK Connect commands that may be transiently flaky are executed with retry logic
(`tenacity`) in `src/stk_mcp/stk_logic/utils.py` (`safe_stk_command`).
- Long-running internal operations are timed with `@timed_operation` for diagnostics.
## Dependencies
Managed with `uv`:
* `agi.stk12` (local wheel from your STK install)
* `mcp[cli]>=1.6.0`
* `uvicorn>=0.30` (explicit for CLI server)
* `rich>=13.7` (CLI table output)
* `typer>=0.15.2`
* `pydantic>=2.11.7`
Notes:
- On macOS (Darwin), STK Engine/Desktop are not supported. The server will start but STK-dependent tools/resources are unavailable.
- The server serializes STK access via a global lock to avoid concurrency issues with multi-threaded access to the STK Engine/Desktop instance.
## Contributing
Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines.
