Which integrations are available for this server?

Uses [Gradio](/mcp/servers/integrations/gradio) as the SDK framework for the FlexSim MCP server application interface. Integrates with FlexSim simulation software through the FlexSimPy [Python](/mcp/servers/integrations/python) SDK, providing tools to control simulations, run experiments, execute FlexScript code, manipulate model nodes, and export results for manufacturing and warehouse analysis.

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.

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

FlexSim MCP Server