CONTAM MCP
CONTAM MCP is a Windows-first MCP server that exposes CONTAM building simulation tools to AI agents, enabling automated project inspection, simulation execution, results analysis, and interactive bridge-mode control of multizone airflow models.
Discovery & File Management
Discover installed CONTAM executables and confirm server access
List CONTAM project files (
.prj,.sim,.wth,.ctm, etc.) in a directoryRetrieve command-line help for
contamx,prjup,simread, andsimcomp
Project Inspection & Management
Inspect
.prjfile structure, metadata, and external referencesDiagnose missing or broken references and suggest candidate replacements
Update referenced weather, contaminant, EWC, WPC, and library file paths
Upgrade older
.prjfiles to newer CONTAM formats viaprjup
Simulation Execution & Results
Validate or fully run a
.prjmodel usingcontamx3.exeCompare two
.simresult files usingsimcompwith configurable verbosityExport human-readable text output from
.simfiles usingsimread
Interactive Bridge Mode (ContamX)
Start a ContamX bridge session for step-by-step co-simulation control
Inspect metadata and state of an active bridge session
List session entities: zones, paths, junctions, AHS systems, control nodes, and more
Advance simulation time with dynamic adjustments (weather, zone temperatures/humidity/concentrations, AHS flows, control nodes) and retrieve outputs (path flows, duct flows, concentrations)
Close and release an active bridge session
Advanced Integration
Leverage
contamxpyfor API-level project inspection and co-simulationDetect availability of Rhino/Grasshopper ANT for model creation workflows
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CONTAM MCP Inspect office_model.prj and check for missing weather file references."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CONTAM Plugin
CONTAM Plugin is a Windows-first public toolkit for using CONTAM from AI coding agents and MCP-capable desktop tools.
It combines three layers in one repository:
a local
stdioMCP server for CONTAM command-line tools and ContamX bridge sessionsa Codex plugin wrapper with workflow guidance for project creation, diagnosis, and simulation
guard scripts for PRJ hygiene, ContamW-safe result settings, and optional
contam_chineselinkage
The project is designed for public use. It helps an agent inspect .prj models, diagnose missing references, run simulations, compare outputs, generate simple ContamW SketchPad layouts, and separate solver failures from ContamW GUI result-display problems.
Quick Use Through MCP
For most users, the easiest setup is an npx-launched local MCP server:
command: npx
args: -y --package github:summer521521/CONTAM_plugin contam-mcpThe binary name remains contam-mcp because it launches the MCP server component. The repository and Codex plugin are named CONTAM_plugin.
Host-specific setup examples are in:
Related MCP server: COMSOL MCP Server
Codex Plugin Use
This repository can also be used as a Codex plugin source because the repository root contains:
.codex-plugin/plugin.json.mcp.jsonskills/contam-mcp/SKILL.mdscripts/start-contam-plugin-mcp.ps1scripts/Invoke-ContamProjectGuard.ps1
The plugin adds a CONTAM workflow skill that tells Codex to:
inspect before editing
keep case-specific data outside the plugin repository
run ContamX input checks before GUI work
keep only one active PRJ in a case folder unless scenarios are intentional
use GUI-safe output settings when the user will run from ContamW
record ContamW Building Check errors and fixes in case-local notes
Main Capabilities
discover bundled or configured CONTAM executables
list
.prj,.sim,.wth,.ctm, and related filesinspect project metadata and external references
diagnose broken project references
update supported
.prjfile referencesclone baseline projects into named scenario folders
create and optionally run small case matrices
apply generated ContamW SketchPad layout data for rectangular rooms, zones, path icons, and source/sink icons
run
contamx3.exeand collect outputsrun a PRJ guard for encoding, result profile, stale-output cleanup, XLog triage, and basic count checks
discover and use optional
contamxpybindings for paper-style ContamX API co-simulationdiscover Rhino/Grasshopper ANT availability for model-creation workflows
upgrade old
.prjfiles withprjup.execompare
.simfiles withsimcomp.exeexport
simreadtext outputsummarize generic CONTAM text outputs for quick result triage
start, inspect, advance, and close ContamX bridge sessions
Project Guard
Before handing a generated PRJ to another user or asking someone to run it in ContamW, run:
.\scripts\Invoke-ContamProjectGuard.ps1 `
-ProjectPath "<case>\model.prj" `
-Mode InputCheck `
-ResultProfile GuiSafeResults `
-CleanOutputs `
-RequireSingleProjectFor a command-line full run:
.\scripts\Invoke-ContamProjectGuard.ps1 `
-ProjectPath "<case>\model.prj" `
-Mode Run `
-ResultProfile GuiSafeResultsThe guard does not prove a hand-drawn SketchPad layout is perfect, but it catches common project-sharing and simulation issues before the GUI step.
Link With contam_chinese
CONTAM_plugin can use the localized executables distributed by contam_chinese.
After extracting a contam_chinese release package, link it for the current PowerShell session:
.\scripts\link-contam-chinese.ps1 -Path "<extracted-contam-chinese-release>"Or persist it for your Windows user:
.\scripts\link-contam-chinese.ps1 -Path "<extracted-contam-chinese-release>" -UserThe launcher honors these variables in order:
explicit tool overrides such as
CONTAMX_PATHCONTAM_HOMECONTAM_CHINESE_HOMEbundled executables in this repository
Use contam_chinese for localized ContamW and Chinese help. Use CONTAM_plugin for MCP automation, project checks, simulation workflows, and report-oriented result extraction.
Repository Layout
.codex-plugin/: Codex plugin manifest.mcp.json: MCP server launch definition for plugin hostsskills/: Codex workflow skill for CONTAM workscripts/: launch, guard, localization-link, setup, and maintenance scriptscontam-mcp/: MCP server source, developer guide, and regression scriptsdocs/: public quickstart and host setup guides.github/workflows/: GitHub Actions workflowsrepository root: bundled CONTAM executables and supporting DLLs
Privacy And CI
This repository includes a privacy check that scans tracked files for personal filesystem paths before public sharing:
npm run privacy:checkRun the basic plugin launcher check with:
npm run plugin:checkRun official regression cases with:
npm run regression:officialExample Prompts
Call discover_contam_installation and confirm CONTAM is available.List CONTAM case files in this folder.Inspect this PRJ file and summarize its references and date range.Run a test input only check for this PRJ.Make this PRJ safe for ContamW Building Check and result review.Run this PRJ and list the generated outputs.Apply a rectangular SketchPad layout to this PRJ so ContamW opens with visible rooms and icons.Run a small case matrix from this baseline model.Analyze this CONTAM xlog or simread text export.Discover whether contamxpy and ANT are available.Start a CONTAM bridge session for this project.Advance the active bridge session by 300 seconds and return path flow updates.
References
Available Tools
15 toolsadvance_contam_bridge_sessionC
Use this when you want to send control/weather adjustments to a running bridge session and optionally advance ContamX to a new simulation time.
Inputs: sessionId (required), targetTimeSeconds, advanceBySeconds, requestConcentrations, +26 more.
close_contam_bridge_sessionA
Use this when you want to end an active ContamX bridge-mode session and release the spawned process and socket.
Inputs: sessionId (required).
compare_contam_sim_resultsC
Use this when you want to compare two CONTAM .sim result files with simcomp.
Inputs: firstSimPath (required), secondSimPath (required), verbosity, timeoutSeconds.
diagnose_contam_projectB
Use this when a CONTAM project fails to run and you want to inspect referenced support files and nearby candidate matches.
Inputs: projectPath (required), workingDirectory, searchRecursively, maxMatchesPerReference.
discover_contam_installationA
Use this when you need to confirm where CONTAM is installed and which executables this MCP server can access.
Inputs: no named parameters.
export_contam_sim_textB
Use this when you need to run simread on a .sim file and you already know the response-script text needed for the interactive prompts.
Inputs: simPath (required), responsesText, responsesFilePath, timeoutSeconds.
get_contam_bridge_sessionB
Use this when you want to inspect the metadata or last-known state of an active ContamX bridge session.
Inputs: sessionId (required).
get_contam_program_helpA
Use this when you want the built-in command-line usage text for a CONTAM executable before deciding which tool or arguments to use.
Inputs: program (required).
inspect_contam_projectA
Use this when you want a quick structural summary of a CONTAM .prj file before editing or running it.
Inputs: projectPath (required).
list_contam_bridge_entitiesB
Use this when you want a concise list of the names and ids available inside an active ContamX bridge session.
Inputs: sessionId (required), category.
list_contam_case_filesC
Use this when you want to find CONTAM project files, result files, or weather files in a directory tree before running a simulation.
Inputs: directory, recursive, extensions, maxResults.
run_contam_simulationB
Use this when you want to validate or run a CONTAM .prj model with ContamX and collect the generated files.
Inputs: projectPath (required), workingDirectory, timeoutSeconds, testInputOnly, +3 more.
start_contam_bridge_sessionB
Use this when you want to launch ContamX in bridge mode and keep an interactive socket session open across multiple MCP calls.
Inputs: projectPath (required), workingDirectory, windFromBridge, volumeFlowBridge, +1 more.
update_contam_project_referencesC
Use this when you need to edit the referenced weather, contaminant, or library files inside a CONTAM .prj file.
Inputs: projectPath (required), weatherFile, contaminantFile, continuousValuesFile, +4 more.
upgrade_contam_projectC
Use this when you need to upgrade an older .prj file to a newer CONTAM project format using prjup.
Inputs: projectPath (required), targetVersion, createBackup, timeoutSeconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Every tool has a clearly distinct purpose with no ambiguity. The tools cover different aspects of CONTAM workflow (installation discovery, project inspection, simulation running, bridge session management, file operations) with precise action-target pairs that prevent misselection.
All tools follow a consistent verb_noun pattern with 'contam' prefix (e.g., discover_contam_installation, run_contam_simulation). The naming is perfectly predictable throughout the set, using snake_case uniformly with clear action verbs.
15 tools is well-scoped for a CONTAM simulation server, covering installation, project management, simulation execution, bridge sessions, and file operations. Each tool earns its place in the domain without being excessive or insufficient.
The toolset provides complete lifecycle coverage for CONTAM projects: discovery, inspection, updating, running simulations, managing bridge sessions, comparing results, and diagnosing issues. No obvious gaps exist for the stated simulation workflow domain.
Maintenance
Related MCP Connectors
MCP server exposing the Backtest360 engine API as tools for AI agents.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to manage, monitor, and diagnose Windows systems through 42 tools across 8 modules, including services, event viewer, task scheduler, processes, network, diagnostics, observability, and safety features.42 npm9MIT
- AlicenseBqualityDmaintenanceMCP Server for COMSOL Multiphysics simulation automation via AI agents.782MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to seamlessly integrate with the Windows operating system, performing tasks such as file navigation, application control, UI interaction, and QA testing via the MCP protocol.-
- AlicenseBqualityDmaintenanceEnables AI clients to execute Windows commands, manage files, query system information, and perform code checks via MCP protocol.241Business Source 1.1