A Model Context Protocol server providing multi-paradigm simulation capabilities through conversational interfaces. The server supports Discrete-Event Simulation via SimPy and System Dynamics modeling via PySD and a PySD-compatible JSON schema.
Text2Sim MCP Server enables Large Language Models to create, validate, and execute simulation models through natural language interfaces. The server processes JSON-structured simulation configurations and returns execution results with comprehensive analytics.
- Discrete-Event Simulation (DES): Process-oriented modeling using SimPy engine
- System Dynamics (SD): Stock-and-flow modeling using PySD and PySD-compatible JSON schema
The Text2Sim MCP Server is an open source project developed by The Cato Bot Company Limited. We believe in transparent, commercially-backed open source development that benefits both users and contributors while supporting sustainable project growth. Community contributions are accepted through standard pull request procedures.
- Python 3.12 or higher
uvpackage manager
curl -LsSf https://astral.sh/uv/install.sh | shpowershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Learn more: astral-sh/uv
git clone https://github.com/IamCatoBot/text2sim-MCP-server.git
cd text2sim-MCP-serveruv sync- Open:
Claude > Settings > Developer > Edit Config > claude_desktop_config.json
- Add the following block:
{
"mcpServers": {
"Text2Sim MCP Server": {
"command": "uv",
"args": [
"--directory",
"PATH_TO_TEXT2SIM_MCP_SERVER",
"run",
"python",
"-m",
"mcp_server"
],
"env": {}
}
}
}Note: Replace
PATH_TO_TEXT2SIM_MCP_SERVERwith the actual path to your cloned repository. If theuvcommand is not found, runwhich uv(Unix) orGet-Command uv(PowerShell) and use the full path in the"command"field.
- Natural language to simulation model conversion
- Multi-round conversation support for iterative model development
- JSON Schema 2020-12 validation for configuration reliability
- Contextual error messages with corrective guidance
- Model persistence across conversation sessions
- Multiple entity types with configurable priorities and attributes
- Resource management with FIFO, priority, and preemptive scheduling
- Entity behavior modeling including balking and reneging
- Resource failure and repair cycle simulation
- Configurable metrics collection and reporting
- PySD-compatible JSON schema
- Stock, flow, and auxiliary variable modeling
- Mathematical expression support via Abstract Syntax Tree structures
- Time-series simulation with configurable parameters
- Integration with PySD Python library ecosystem
- Simulation metrics including wait times, utilization rates, and throughput
- Statistical analysis with warmup periods and confidence intervals
- Multi-mode validation with partial, strict, and structural checking
- Schema-specific error reporting and correction guidance
- Model storage and retrieval with metadata tracking
- JSON export functionality for model sharing and backup
- Automatic schema detection for DES and SD model types
- Version management with conflict resolution
- Context-aware schema documentation with examples
- Multiple detail levels (brief, standard, detailed)
- Domain-specific modeling patterns and workflows
- Integrated help system accessible through MCP tools
- Regex-based distribution parsing without code execution
- Input validation against formal JSON schemas
- Secure error handling without internal state exposure
Text2Sim MCP Server v2.6.0 features a completely refactored modular architecture that improves maintainability, testability, and extensibility:
mcp_server/
├── __init__.py # Package exports and version info
├── server.py # Main server entry point
├── registry.py # Centralized tool registration
├── shared/ # Common utilities
│ ├── error_handlers.py # Standardized error handling
│ ├── response_builders.py # Response formatting utilities
│ └── integration_layer.py # SD integration with fallbacks
└── tools/ # Domain-specific tool modules
├── des_tools.py # DES simulation tools
├── sd_tools.py # SD simulation tools
├── model_mgmt_tools.py # Model lifecycle management
├── validation_tools.py # Validation and help tools
└── template_tools.py # Template management tools
- Separation of Concerns: Each domain has its own focused module
- Standardized Error Handling: Consistent error responses with actionable guidance
- Enhanced Integration: Robust SD integration with graceful fallbacks
- Professional Standards: Comprehensive documentation and type hints
- Extensibility: Easy to add new simulation paradigms or tools
The server exposes 16 tools across 5 categories through the Model Context Protocol:
simulate_des - Execute Discrete-Event Simulation models
- Accepts JSON configuration with entity types, resources, and processing rules
- Returns simulation results with metrics and statistical analysis
simulate_sd - Execute System Dynamics models
- Accepts PySD-compatible abstractModel JSON format
- Returns time-series data and model execution metadata
run_multiple_simulations - Execute multiple simulation replications
- Runs multiple independent simulation runs with statistical analysis
- Returns confidence intervals, variability measures, and reliability scoring
- Supports seed-based random number control for reproducible results
validate_model - Validate simulation model configurations
- Supports both DES and SD model validation with auto-detection
- Provides detailed error reports with correction suggestions
- Multiple validation modes: partial, strict, and structural
help_validation - Get validation guidance
- Shows all available validation tools and when to use each one
- Provides troubleshooting guidance for validation errors
- Includes schema type detection and validation mode explanations
get_schema_help - Access comprehensive schema documentation
- Returns structured documentation for schema sections with examples
- Supports nested section paths (e.g., "processing_rules.steps")
- Multiple detail levels: brief, standard, and detailed
- Domain-specific examples and workflow guidance
save_model - Store models with metadata
- Automatic naming with domain detection
- Metadata tracking including validation status and tags
- Version management with conflict resolution
load_model - Retrieve stored models
- List all saved models with filtering options
- Load specific models by name or identifier
- Integration with last-loaded state tracking
export_model - Export models to JSON
- Multiple output formats for different use cases
- Conversation-ready templates for session sharing
- Token count estimation for LLM context management
list_templates - Browse available model templates
- Lists pre-built templates for both DES and SD models
- Filter by schema type, domain, or complexity level
- Includes template descriptions and use cases
load_template - Retrieve specific templates
- Load template configurations by name or template ID
- Returns ready-to-use model configurations
- Supports both DES and SD template formats
save_template - Save models as reusable templates
- Store validated models as templates for future use
- Automatic template naming with metadata
- Template sharing and organization capabilities
delete_template - Remove user templates
- Safe deletion with confirmation requirements
- Protects built-in templates from accidental removal
- Provides backup recommendations
get_sd_model_info - Analyze System Dynamics models
- Provides detailed analysis of SD model structure without simulation
- Returns complexity metrics and variable information
- Validates abstractModel format and reports structure analysis
convert_vensim_to_sd_json - Convert Vensim models to PySD JSON
- Converts Vensim .mdl files to PySD-compatible abstractModel format
- Handles model translation and format validation
- Integration with PySD's Vensim translation capabilities
delete_model - Safe model deletion
- Remove saved models with confirmation requirements
- Provides model metadata before deletion
- Includes undo suggestions and safety features
Text2Sim MCP Server uses formal JSON Schema validation (Draft 2020-12) to ensure simulation model correctness and provide structured error reporting. The server supports two distinct JSON formats optimized for their respective simulation paradigms.
The server uses a SimPy-compatible JSON schema for Discrete-Event Simulation models. This format provides declarative configuration that maps directly to SimPy's native capabilities.
{
"run_time": 480,
"entity_types": {
"customer": {
"probability": 1.0,
"value": {"min": 10, "max": 50},
"priority": 5
}
},
"resources": {
"server": {
"capacity": 2,
"resource_type": "fifo"
}
},
"processing_rules": {
"steps": ["server"],
"server": {
"distribution": "uniform(5, 10)"
}
}
}- Entity Types: Define different classes of entities with probabilities, values, priorities, and custom attributes
- Resources: Specify system resources with capacity limits and queuing disciplines (FIFO, priority, preemptive)
- Processing Rules: Configure sequential processing steps with service time distributions and conditional routing
- Behavioral Rules: Support for balking, reneging, resource failures, and complex routing logic
- FIFO: First-in-first-out queuing (SimPy Resource)
- Priority: Priority-based queuing (SimPy PriorityResource)
- Preemptive: Preemptive priority queuing (SimPy PreemptiveResource)
For detailed documentation of the DES JSON format, see schemas/DES/README.md.
The server uses a PySD-compatible JSON schema for System Dynamics simulations. This format provides direct compatibility with the PySD Python library ecosystem.
{
"abstractModel": {
"originalPath": "model_name.json",
"sections": [{
"name": "__main__",
"type": "main",
"elements": [
{
"name": "Stock_Name",
"components": [{
"type": "Stock",
"ast": {
"syntaxType": "IntegStructure",
"flow": {"syntaxType": "ReferenceStructure", "reference": "Flow_Name"},
"initial": {"syntaxType": "ReferenceStructure", "reference": "1000"}
}
}],
"units": "items"
}
]
}]
}
}- Stock: Accumulation variables that integrate flows over time
- Flow: Rate variables that change stock values
- Auxiliary: Calculated variables derived from other variables
The PySD format supports two approaches for mathematical expressions:
- Simple References: String-based expressions (e.g.,
"Birth_Rate - Death_Rate") - Arithmetic Structures: Explicit mathematical structures with defined operators and arguments
For detailed documentation of the PySD JSON format, see docs/PYSD_JSON_SCHEMA_INTEGRATION.md, docs/PYSD_AST_STRUCTURES_GUIDE.md, and schemas/SD/README.md.
Text2Sim is structured into modular components:
- MCP Server – Handles natural language requests via MCP.
- Discrete-Event Simulation (DES) Module
- Simulation Model – Core SimPy engine that executes process flows.
- Entity Class – Represents units flowing through the system.
- Process Steps – Encapsulate logic for each process stage.
- Metrics Collector – Gathers statistics like wait times and throughput.
- Secure Distribution Parser – Parses probability distributions safely.
- System Dynamics (SD) Module
- PySD Integration – Executes models using PySD-compatible abstractModel JSON format.
- Schema Validation – Validates models against abstract_model_v2.json schema.
- Single-Schema Architecture – Direct PySD workflow compatibility without format conversion.
Additional technical documentation is available:
docs/PYSD_JSON_SCHEMA_INTEGRATION.md- PySD JSON format specificationdocs/PYSD_AST_STRUCTURES_GUIDE.md- AST structure patterns and best practicesschemas/SD/README.md- System Dynamics schema documentationschemas/DES/README.md- Discrete-Event Simulation schema filesSINGLE_SCHEMA_ARCHITECTURE.md- Architecture overview and design decisions
-
No
eval()usage
Regex-based parsing prevents arbitrary code execution. -
Input Validation
Distribution types, parameters, and model configurations are validated before execution. -
Robust Error Handling
Errors are reported cleanly without leaking internal state.
Text2Sim MCP Server is a project under active development. While we strive for accuracy and stability, please be aware of the following:
- Work in Progress: The software is continuously evolving. Features may change, and you may encounter bugs or incomplete functionality. We welcome bug reports and contributions to help us improve!
- LLM-Powered Tool: This server is designed to be used with Large Language Models (LLMs). The quality of the simulation models and the accuracy of the results depend heavily on the LLM's capabilities.
- Verify Your Results: Always critically review and validate any simulation models and their outputs. The results should be used as a guide and not as a substitute for professional validation.
We are excited for you to use Text2Sim and hope you find it valuable. Your feedback is crucial to its development.
Contributions are accepted through standard fork-and-pull-request procedures. Bug reports and feature suggestions can be submitted via the project issue tracker.
Major changes should be discussed before implementation. The project is under active development and architectural decisions may change.
This project is licensed under the MIT License. See the LICENSE file for details.
For academic use, cite as:
Maniatis, N. (2025). Text2Sim MCP Server (v2.6.0). https://github.com/IamCatoBot/text2sim-MCP-server Copyright The Cato Bot Company Limited and contributors. Licensed under MIT.