{"id":28769071,"url":"https://github.com/alti3/stk-mcp","last_synced_at":"2026-04-09T04:01:38.839Z","repository":{"id":285983689,"uuid":"959871810","full_name":"alti3/stk-mcp","owner":"alti3","description":"An MCP server allowing LLMs to interact with Ansys/AGI STK - Digital Mission Engineering Software","archived":false,"fork":false,"pushed_at":"2025-10-08T14:08:26.000Z","size":1825,"stargazers_count":16,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-08T15:16:34.547Z","etag":null,"topics":["ansys","mcp","mcp-server","mcp-servers","mission-planning","orbit","orbital-mechanics","orbital-simulation","satellite","simulation","stk"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alti3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-04-03T13:42:32.000Z","updated_at":"2025-10-08T14:08:30.000Z","dependencies_parsed_at":"2025-04-03T18:22:23.895Z","dependency_job_id":"51c4d1cf-961a-4192-8938-d9b3c8995159","html_url":"https://github.com/alti3/stk-mcp","commit_stats":null,"previous_names":["alti3/stk-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alti3/stk-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alti3%2Fstk-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alti3%2Fstk-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alti3%2Fstk-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alti3%2Fstk-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alti3","download_url":"https://codeload.github.com/alti3/stk-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alti3%2Fstk-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31584817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansys","mcp","mcp-server","mcp-servers","mission-planning","orbit","orbital-mechanics","orbital-simulation","satellite","simulation","stk"],"created_at":"2025-06-17T13:03:37.750Z","updated_at":"2026-04-09T04:01:38.833Z","avatar_url":"https://github.com/alti3.png","language":"Python","funding_links":[],"categories":["🤖 AI/ML","Other Tools and Integrations","Scientific Research Tools"],"sub_categories":["How to Submit"],"readme":"# STK-MCP\n\n[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/) [![MCP Version](https://img.shields.io/pypi/v/mcp.svg)](https://pypi.org/project/mcp/)\n\nSTK-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.\n\n\nThis project allows controlling STK via an MCP server, supporting both STK Desktop (Windows only) and STK Engine (Windows \u0026 Linux). It utilizes `FastMCP` from the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).\n\n## Overview\n\nThe 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.\n\nThe 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`.\n\n## Features\n\n*   CLI entry point powered by `Typer`.\n*   Dual mode operation: STK Engine (Windows/Linux) and STK Desktop (Windows).\n*   OS-aware: Desktop mode auto-disabled on non-Windows platforms.\n*   Managed lifecycle: STK instance is started/stopped with the MCP server.\n*   Tool discovery: `list-tools` command enumerates available MCP tools.\n*   Modular architecture: CLI (`cli.py`), MCP (`app.py`), STK logic (`stk_logic/`), and MCP tools (`tools/`).\n\n## Prerequisites\n\n*   **Operating System:** Windows or Linux. STK Desktop mode requires Windows.\n*   **Python:** Version 3.12 or higher.\n*   **Ansys/AGI STK:** Version 12.x Desktop or Engine installed.\n*   **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.\n\n## Installation\n\n1.  Clone the repository\n    ```bash\n    git clone \u003crepository-url\u003e\n    cd stk-mcp\n    ```\n2.  Create and activate a virtual environment\n    ```bash\n    # Create the virtual environment\n    uv venv\n\n    # Activate it\n    # On Windows (in PowerShell/CMD):\n    # .venv\\Scripts\\activate\n    # On Linux (in bash/zsh):\n    source .venv/bin/activate\n    ```\n3.  Add dependencies with uv (preferred)\n    - Add the STK Python wheel from your STK installation (local file):\n    ```bash\n    uv add ./agi.stk12-12.10.0-py3-none-any.whl\n    # or: uv add path/to/your/STK/CodeSamples/Automation/Python/agi.stk12-*.whl\n    ```\n4.  Sync the environment (installs deps from `pyproject.toml`)\n    ```bash\n    uv sync\n    ```\n\n## Usage\n\nThis project is a command-line application. Ensure your virtual environment is activated before running commands.\n\n### Listing Available Tools\n\n```bash\nuv run -m stk_mcp.cli list-tools\n```\nPrints a table of tool names and their descriptions.\n\n### Running the MCP Server\n\nUse the `run` command to start the MCP server. The server will automatically start and manage an STK instance.\n\nRun with `uv run` so you don’t need to install the package into site-packages.\n\n**1) STK Engine (recommended for automation, Windows/Linux):**\n```bash\nuv run -m stk_mcp.cli run --mode engine\n```\n\n**2) STK Desktop (Windows only, shows GUI):**\nEnsure STK Desktop is closed; the server will launch and manage its own instance.\n```bash\nuv run -m stk_mcp.cli run --mode desktop\n```\n\nThe server will start, initialize STK, and listen for MCP connections on `http://127.0.0.1:8765` by default.\n\n**3. Command Options:**\nYou can see all options with the `--help` flag:\n```bash\nstk-mcp run --help\n```\n\n### Interacting with the Server\nOnce the server is running, you can connect to it using any MCP client, such as the MCP Inspector.\n\n1.  Open the MCP Inspector URL provided in the console (e.g., `http://127.0.0.1:8765`).\n2.  Find the \"STK Control\" server in the list.\n3.  Use the \"Tools\" section to execute `setup_scenario`, `create_location`, and `create_satellite`.\n\n### Stopping the Server\nPress `Ctrl+C` in the terminal where the server is running. The lifecycle manager will automatically close the STK Engine or Desktop instance.\n\n## MCP Tools and Resources\n\nThe server exposes the following MCP tools/resources.\n\n| Name             | Kind     | Description                                                                                   | Desktop (Windows) | Engine (Windows) | Engine (Linux) |\n|------------------|----------|-----------------------------------------------------------------------------------------------|-------------------|------------------|----------------|\n| `setup_scenario` | Tool     | Create/configure an STK Scenario; sets time period and rewinds animation.                    | Yes               | Yes              | Yes            |\n| `create_location`| Tool     | Create/update a `Facility` (default) or `Place` at latitude/longitude/altitude (km).         | Yes               | Yes              | Yes            |\n| `create_satellite`| Tool    | Create/configure a satellite from apogee/perigee (km), RAAN, and inclination; TwoBody prop.  | Yes               | Yes              | No             |\n\nResources:\n\n| Name | Kind | Description | Desktop (Windows) | Engine (Windows) | Engine (Linux) |\n|------|------|-------------|-------------------|------------------|----------------|\n| `resource://stk/objects` | Resource | List all objects in the active scenario. Returns JSON records: `{name, type}`. | Yes | Yes | Yes |\n| `resource://stk/objects/{type}` | Resource | List objects filtered by `type` (e.g., `satellite`, `facility`, `place`, `sensor`). Returns JSON records. | Yes | Yes | Yes |\n| `resource://stk/health` | Resource | Report basic state: mode, scenario name, and object counts. | Yes | Yes | Yes |\n| `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 |\n| `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 |\n\nExamples:\n\n- Read all objects: `resource://stk/objects`\n- Read only satellites: `resource://stk/objects/satellite`\n- Read ground locations: `resource://stk/objects/location` (alias for facilities and places)\n\nAccess and LLA examples:\n\n- Compute access: `resource://stk/analysis/access/Satellite/ISS/Facility/Boulder`\n- Get ISS LLA (60 s): `resource://stk/reports/lla/Satellite/ISS` (optional `step_sec` argument)\n\n## Configuration \u0026 Logging\n\nConfiguration is centralized in `src/stk_mcp/stk_logic/config.py` using `pydantic-settings`.\nDefaults can be overridden with environment variables (prefix `STK_MCP_`).\n\n- `STK_MCP_DEFAULT_HOST` (default `127.0.0.1`)\n- `STK_MCP_DEFAULT_PORT` (default `8765`)\n- `STK_MCP_LOG_LEVEL` (default `INFO`)\n- `STK_MCP_DEFAULT_SCENARIO_NAME` (default `MCP_STK_Scenario`)\n- `STK_MCP_DEFAULT_START_TIME` (default `20 Jan 2020 17:00:00.000`)\n- `STK_MCP_DEFAULT_DURATION_HOURS` (default `48.0`)\n\nLogging is standardized via `src/stk_mcp/stk_logic/logging_config.py`. The CLI uses\nthis configuration, producing structured logs with timestamps, levels, and context.\n\n## Implementation Notes\n\n- STK access is serialized with a global lock to avoid concurrency issues.\n- Common STK-availability checks are handled via decorators in\n  `src/stk_mcp/stk_logic/decorators.py` (`@require_stk_tool` and `@require_stk_resource`).\n- STK Connect commands that may be transiently flaky are executed with retry logic\n  (`tenacity`) in `src/stk_mcp/stk_logic/utils.py` (`safe_stk_command`).\n- Long-running internal operations are timed with `@timed_operation` for diagnostics.\n\n## Dependencies\n\nManaged with `uv`:\n\n*   `agi.stk12` (local wheel from your STK install)\n*   `mcp[cli]\u003e=1.6.0`\n*   `uvicorn\u003e=0.30` (explicit for CLI server)\n*   `rich\u003e=13.7` (CLI table output)\n*   `typer\u003e=0.15.2`\n*   `pydantic\u003e=2.11.7`\n\nNotes:\n- On macOS (Darwin), STK Engine/Desktop are not supported. The server will start but STK-dependent tools/resources are unavailable.\n- The server serializes STK access via a global lock to avoid concurrency issues with multi-threaded access to the STK Engine/Desktop instance.\n\n## Contributing\n\nContributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falti3%2Fstk-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falti3%2Fstk-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falti3%2Fstk-mcp/lists"}