STK-MCP

by alti3

40 stars
704 downloads
Not rated
GitHub

About

An MCP server allowing LLMs to interact with Ansys/AGI STK - Digital Mission Engineering Software

Details

Author
alti3
GitHub stars
40
Downloads
704
Categories
Other

Jump to

- CLI powered by Typer for tool listing and server control.
- Dual mode: STK Engine (Windows/Linux) and STK Desktop (Windows).
- OS-aware: desktop mode auto-disabled on non-Windows platforms.
- Managed lifecycle: STK instance started/stopped with the MCP server.
- Tool discovery via list-tools command enumerating available MCP tools.
- Modular architecture separating CLI, MCP app, STK logic, and tools.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name STK-MCP
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Clone the repository, create a virtual environment, add the STK Python wheel from your STK installation, and run uv sync. Then list available tools with uv run -m stk_mcp.cli list-tools and start the server with uv run -m stk_mcp.cli run --mode engine (or --mode desktop on Windows). The server listens on http://127.0.0.1:8765 by default; stop it with Ctrl+C.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "stk-mcp": {
            "stk-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

McpServers

{
    "stk-mcp": {
        "command": "uv",
        "args": [
            "venv"
        ]
    }
}

STK-MCP

Python Version MCP Version

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 (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.

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

    git clone <repository-url>

    cd stk-mcp

2. Create and activate a virtual environment
    # 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):
    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)
    uv sync

Usage

This project is a command-line application. Ensure your virtual environment is activated before running commands.

Listing Available Tools

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):

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.

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:

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 file for guidelines.

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "stk-mcp": {
            "stk-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other

Reactive Resume

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5k
Other