Skip to main content
Glama
FlexSim MCP Server

FlexSim MCP Server

by SethGame

title: FlexSim MCP Server emoji: ⚙️ colorFrom: blue colorTo: green sdk: gradio sdk_version: "5.0.0" app_file: app.py pinned: false

FlexSim MCP Server (incl. FlexSimPy)

Track

Control and automate FlexSim simulations via the Model Context Protocol (MCP). This repository exposes a FastMCP server that launches FlexSim (via FlexSimPy) and provides tools to open models, run/stop, step, query/set node values, evaluate FlexScript, export results, and more.

Why this matters

  • Bridges digital twins and AI assistants (Claude/Cursor) for manufacturing/warehouse analysis and “what-if” studies.

  • Demonstrates robust systems engineering: GUI process orchestration, async I/O, protocol handling, Windows quirks, and reproducible automation.


Related MCP server: anylogicPLE-mcp

Design

┌─────────────────────┐       JSON-RPC        ┌─────────────────────┐
│    MCP Client       │◄────────────────────► │    MCP Server       │
│  (Claude/Cursor)    │     stdin/stdout      │  (flexsim_mcp.py)   │
└─────────────────────┘                       └──────────┬──────────┘
                                                         │
                                                         │ Python API
                                                         ▼
                                              ┌─────────────────────┐
                                              │     FlexSimPy       │
                                              │   (Python SDK)      │
                                              └──────────┬──────────┘
                                                         │
                                                         │ COM/IPC
                                                         ▼
                                              ┌─────────────────────┐
                                              │      FlexSim        │
                                              │  (Simulation Engine)│
                                              └─────────────────────┘

Features

  • MCP server entry point: mcp_server/flexsim_mcp.py

  • Tools exposed:

    • Simulation control: flexsim_open_model, flexsim_reset, flexsim_run, flexsim_run_to_time, flexsim_stop, flexsim_step, flexsim_get_time

    • Model/script: flexsim_evaluate, flexsim_compile, flexsim_save_model, flexsim_new_model

    • Node access: flexsim_get_node_value, flexsim_set_node_value

    • Results/stats: flexsim_get_statistics, flexsim_export_results

  • Logging: mcp_server/flexsim_mcp.log

  • Reproducible environment: uv sync

  • FlexSimPy build automation: utility/build_automation.py

  • Integration tests: tests/integration/test_mcp_client.py (stdio-based MCP client)

  • GUI sanity test: utility/integration_test.py

  • Configurable behavior via config.toml and environment overrides


Requirements

  • OS: Windows

  • Python: 3.12 (default; configurable via config.toml or FLEXSIM_PYTHON_VERSION)

  • Package manager: uv (https://astral.sh)

  • FlexSim:

    • Real runs require a local FlexSim installation (or repo-local mirror in FlexSimDev/program)

    • FlexSimPy SDK submodule is provided at depends/FlexSimPy (see .gitmodules)


Quickstart

Guided setup (recommended)

# From the repo root
python setup_mcp_server.py

# The setup helper will:
# - Summarize your configuration (install locations, Python version, submodule presence)
# - Ensure `uv` is installed and run `uv sync`
# - Build/install FlexSimPy via `utility/build_automation.py`
# - Optionally run a GUI integration sanity test
# - Print next steps to run the MCP server and tests

Manual setup

# 1) Install dependencies
uv sync

# 2) Check (and optionally build) FlexSimPy
uv run python utility/build_automation.py --status
# To force a build with a specific Python version:
# uv run python utility/build_automation.py --python-version 3.12

# 3) Launch MCP server in test mode (keeps the process alive; launches FlexSim on first tool call)
uv run mcp_server/flexsim_mcp.py --test-mode

# 4) Run integration tests (spawns the server as a subprocess; stdio MCP client)
uv run python tests/integration/test_mcp_client.py

Configuration

Primary configuration lives in config.toml (repo root). You can also override at runtime using environment variables.

Example (excerpt from config.toml):

[flexsim]
install_path = "FlexSimDev/program"
src_path = "C:\\Program Files\\FlexSim 2025 Update 2"

[python]
version = "3.12"

[server]
name = "FlexSimPy MCP Server"
version = "0.1.0"
http_endpoint = "http://127.0.0.1:8088/mcp"

[session]
reuse_policy = "singleton"

[logging]
level = "INFO"
log_file = "flexsim_mcp.log"

[build]
flexsimpy_dir = "depends/FlexSimPy"
auto_build = true
auto_install = true

Environment overrides (see utility/config.py):

  • FLEXSIM_CONFIG_PATH – path to an alternate config.toml

  • FLEXSIM_INSTALL_PATH – override FlexSim program path

  • FLEXSIM_PYTHON_VERSION – override Python version for FlexSimPy

  • FLEXSIM_LOG_LEVEL – override logging level


Running the MCP server

Two modes:

  • Test mode (interactive; no stdio protocol)

uv run mcp_server/flexsim_mcp.py --test-mode
# Keeps running; FlexSim launches on first tool call; intended for manual testing
  • MCP stdio mode (default when no flags are passed)

uv run mcp_server/flexsim_mcp.py
# Expects MCP JSON-RPC messages via stdin/stdout; used by clients/tests

Client configuration (for Claude/Cursor/etc.):

{
  "mcpServers": {
    "flexsim": {
      "command": "uv",
      "args": [
        "--directory",
        "<repo-flexsim_mcp>/",
        "run",
        "mcp_server/flexsim_mcp.py"
      ]
    }
  }
}

Example tool calls (JSON-RPC via MCP)

Open a model

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{
   "name":"flexsim_open_model",
   "arguments":{"params":{
     "model_path":"C:/path/to/Model.fsm"
   }}
 }}

Run to time and read time

{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"flexsim_run_to_time","arguments":{"params":{"target_time":300}}}}

{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"flexsim_get_time"}}

Evaluate FlexScript

{"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"flexsim_evaluate","arguments":{"params":{
   "script":"getmodeltime()"
 }}}}

Get/Set node value

{"jsonrpc":"2.0","id":5,"method":"tools/call",
 "params":{"name":"flexsim_get_node_value","arguments":{"params":{
   "node_path":"Model/Queue1/stats/input"
 }}}}

{"jsonrpc":"2.0","id":6,"method":"tools/call",
 "params":{"name":"flexsim_set_node_value","arguments":{"params":{
   "node_path":"Model/Processor1/variables/processtime",
   "value":5.0
 }}}}

More FlexScript examples and behavior: see eval-flexscript.md.


Tests

Integration tests (stdio client; verifies tools and basic run sequence):

uv run python tests/integration/test_mcp_client.py
# Test 1: open model; Test 2: run for 20s, stop, verify time > 0

GUI sanity test (manual, interactive menu):

uv run python utility/integration_test.py
# Launches FlexSim GUI and provides simple interactive actions

Repository structure

  • mcp_server/flexsim_mcp.py — FastMCP server and FlexSimPy controller logic (entry point)

  • utility/

    • config.py — configuration loader with env overrides

    • build_automation.py — FlexSimPy build/install orchestration (MSBuild resolution, .pyd install)

    • copy_flexsim.py — copies a FlexSim installation into FlexSimDev/ (uses flexsim.src_path)

    • integration_test.py — GUI-backed sanity test (suppresses CEF stderr, safe cleanup)

    • utility.py — helpers: suppress stderr, kill FlexSim processes, force exit

  • tests/integration/

    • test_mcp_client.py — async stdio client that starts the server and calls tools

    • README.md — test descriptions and sample outputs

  • depends/FlexSimPy — FlexSimPy SDK submodule

  • FlexSimDev/program — optional repo-local mirror of FlexSim install

  • config.toml, mcp_server_config.json, AGENTS.md, eval-flexscript.md


Batch Experiment Orchestrator (Design)

A high-impact enhancement to run parameter sweeps with replications, gather metrics, and export a unified summary.csv (and manifest.json), enabling “what-if” studies at scale.

  • Design document: Batch_Experiment_Orchestrator.md

  • Status: design in-repo; implementation planned (not yet in flexsim_mcp.py)

  • MVP tool (planned): flexsim_run_experiments with parameter list, seeds/replications, run_to_time, stats, artifact_dir


Troubleshooting

  • FlexSim not found:

    • Update flexsim.install_path in config.toml or set FLEXSIM_INSTALL_PATH

    • Optionally use utility/copy_flexsim.py to mirror an existing install into FlexSimDev/

  • FlexSimPy unavailable:

    • Check status: uv run python utility/build_automation.py --status

    • Rebuild for the active Python version and ensure the .pyd is installed

  • Stdio client issues:

    • Ensure you run the server without --test-mode when using stdio clients

    • Check mcp_server/flexsim_mcp.log for details

  • GUI noise (CEF) or shutdown issues:

    • The utilities suppress CEF stderr and force a safe interpreter exit when needed

Available Tools

15 tools
flexsim_compileB

Compile the model (check for FlexScript errors).

Inputs: no named parameters. Returns: result

flexsim_evaluateB

Execute FlexScript code.

Args:
    script: FlexScript code to evaluate

Examples:
    script='Model.find("Queue1").subnodes.length'  # Get queue content
    script='getmodeltime()'  # Get simulation time

Inputs: params (required). Returns: result

flexsim_export_resultsB

Export simulation results to file.

Args:
    export_path: Path to save results
    format: Export format (csv, xlsx, json)

Example:
    export_path="C:/Results/output.csv"
    format="csv"

Inputs: params (required). Returns: result

flexsim_get_node_valueC

Get value from FlexSim tree node.

Args:
    node_path: Path to node (e.g., "Model/Queue1/stats/input")

Inputs: params (required). Returns: result

flexsim_get_statisticsB

Get simulation statistics and performance metrics.

Inputs: no named parameters. Returns: result

flexsim_get_timeB

Get current simulation time.

Inputs: no named parameters. Returns: result

flexsim_new_modelB

Create a new blank model.

Inputs: no named parameters. Returns: result

flexsim_open_modelB

Open a FlexSim model file.

Args:
    model_path: Path to .fsm or .fsx file

Example:
    model_path="C:/Models/warehouse.fsm"

Inputs: params (required). Returns: result

flexsim_resetB

Reset simulation to initial state (time = 0).

Inputs: no named parameters. Returns: result

flexsim_runB

Start running the simulation continuously.

Inputs: no named parameters. Returns: result

flexsim_run_to_timeA

Run simulation until reaching target time.

Args:
    target_time: Target simulation time in seconds
    fast_mode: Run at maximum speed (default: True). Set to False for real-time GUI updates.

Example:
    target_time=3600  # Run for 1 hour

Inputs: params (required). Returns: result

flexsim_save_modelB

Save the current model.

Args:
    save_path: Path to save (optional, uses current if not provided)

Example:
    save_path="C:/Models/warehouse_v2.fsm"

Inputs: params (required). Returns: result

flexsim_set_node_valueB

Set value in FlexSim tree node.

Args:
    node_path: Path to node
    value: New value to set

Example:
    node_path="Model/Processor1/variables/processtime"
    value=5.0

Inputs: params (required). Returns: result

flexsim_stepB

Step through simulation events.

Args:
    steps: Number of events to step (1-1000, default: 1)

Example:
    steps=10  # Advance 10 events

Inputs: params (required). Returns: result

flexsim_stopA

Stop the running simulation.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. For example, flexsim_run starts continuous simulation, flexsim_run_to_time runs to a specific time, and flexsim_step advances by events, while flexsim_compile checks for errors versus flexsim_evaluates executes code. The descriptions clearly differentiate each tool's function.

    Naming Consistency5/5

    All tools follow a consistent 'flexsim_verb' or 'flexsim_verb_noun' pattern with snake_case throughout. Examples include flexsim_open_model, flexsim_get_time, and flexsim_set_node_value, making them predictable and readable.

    Tool Count5/5

    With 15 tools, the set is well-scoped for a FlexSim simulation server, covering essential operations like model management, simulation control, data access, and result export. Each tool earns its place without being overwhelming or insufficient.

    Completeness5/5

    The tool surface provides complete coverage for the FlexSim domain, including model creation, opening, saving, simulation control (run, stop, reset, step), time and statistics retrieval, node value manipulation, code evaluation, and result export. There are no obvious gaps that would hinder agent workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents such as Claude to drive SolidWorks through its COM API using natural language, creating parts and assemblies, sketching geometry, and adding features without clicking menus. Also supports running arbitrary API scripts and verifying results through model reports, rendered views, interference checks, and exports.
      1
      MIT