This function is experimental. Users should check inputs and outputs carefully before relying on them, particularly when inputs are AI generated.
Why use an MCP Server?
MCP ("Model Context Protocol") is an open-source standard for connecting AI applications to external systems. See https://modelcontextprotocol.io/ for more details on this protocol.
Vulcan's MCP Server enables direct access to selected Vulcan functionality for desktop AI clients (e.g., Claude or Cursor) or command-line scripts - without using the browser app:
Turn CSV files in the format created by the Geometry section (saved in input/base_models) into HEM input files (saved in input/batch_parameters/base_json)
View and edit the batch parameter files used in the Scenarios section, and create a Batch Config
Run a Batch Config, and check for progress and available outputs
Calculate metrics in a similar way to the Results section
This can be helpful to automate design option testing, input sensitivity checks, or deeper analysis of outputs.
Set up Instructions
Requirements
Vulcan's MCP helper is installed with npm, so requires Node.js 18 or later and npm. For help installing Node.js and npm, see https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
You will also need to create a vulcan-mcp-config.json file. This file can be created in the Integrations menu in the Profile menu dropdown, by clicking Generate Config File. It will be created in your workspace, as the MCP server interacts with files there in the same way as the browser app. This file contains a license_token associated with your Vulcan authentication, that remains valid for 30 days.
Installation
Install the helper globally:
npm install -g @vulcan-energy/mcp-helper
From your Vulcan workspace, start the helper:
vulcan-mcp-helper
By default, the helper runs at http://127.0.0.1:5000/mcp.
Cursor Desktop configuration
Add the following JSON to your Cursor MCP configuration (~/.cursor/mcp.json or Cursor settings). This is optional to enable direct tool use within Cursor.
{
"mcpServers": {
"vulcan": {
"url": "http://127.0.0.1:5000/mcp"
}
}
}
Restart Cursor after changing MCP configuration.
Claude Code configuration
Once Claude Code and vulcan-mcp-helper are installed, connect Claude Code to the local MCP URL shown by the helper.
To verify that the helper is running, open:
curl http://127.0.0.1:5000/health
Tool use
Start the MCP server
To start the server, from your workspace run:
vulcan-mcp-helper
Or specify the config and port:
vulcan-mcp-helper --config /path/to/vulcan-mcp-config.json --port 5000
CLI options:
--config <path> - Path to config file (default: ./vulcan-mcp-config.json)
--port <port> - Port to listen on (default: 5000, or HELPER_PORT env var if provided)
--help, -h - Show help message
Expected outputs:
[MCP Helper] Config loaded from: /path/to/vulcan-mcp-config.json
[MCP Helper] Workspace: /path/to/workspace
[MCP Helper] Server running on http://127.0.0.1:5000
[MCP Helper] MCP endpoint: http://127.0.0.1:5000/mcp
Available tools
The following tools are available for use. When vulcan-mcp-helper is integrated as an MCP server with Cursor or Claude, the client will handle connecting to the server, discovering tools, calling them with proper formatting and handling responses.
vulcan_merge_csv_to_json: Convert CSV geometry (such as that created by the Geometry section) to JSON inputs that can be run in HEM
vulcan_list_parameters: List parameter categories
category (optional, string): Filter by category name (e.g., base_json, heat_source_wet)
vulcan_view_parameter: View parameter details
category (required, string): Parameter category (e.g., heat_source_wet, controls, base_json)
parameter_id (required, string): Parameter ID (filename without .json extension)
vulcan_save_parameter: Create/edit parameters
category (required, string): Parameter category
parameter_id (required, string): Parameter ID (filename without .json extension)
content (required, object): Parameter JSON content
markdown_content (optional, string): Optional markdown documentation
vulcan_create_batch_config: Create batch configurations
config_name (required, string): Configuration name (saved as {config_name}.json)
base_model (required, string): Base model filename (without .json extension)
weather_file (required, string): Weather file name (with or without .epw extension)
wrapper (optional, string): Model wrapper (e.g., fhs_compliance, fhs_assumptions, passthrough)
parameters (required, object): Object mapping category to array of parameter IDs
vulcan_run_batch: Run batch simulations asynchronously
config_name (required, string): Configuration name (with or without .json extension)
job_id (optional, string): Custom job ID (defaults to mcp_{uuid})
vulcan_get_batch_status: Check batch progress
job_id (optional, string): Job ID returned from vulcan_run_batch
config_name (optional, string): Configuration name (alternative to job_id)
Note: Either job_id or config_name must be provided.
vulcan_list_batch_models: List models from completed batch
config_name (required, string): Configuration name (with or without .json extension)
vulcan_list_csv_columns: List CSV columns for a model
config_name (required, string): Configuration name (with or without .json extension)
model_name (required, string): Model name (e.g., "scenario_1_0")
vulcan_calculate_metrics: Calculate metrics from standard core result files created by model runs. For compliance-only outputs, use the Vulcan app or inspect the relevant report files directly.
config_name (required, string): Configuration name (with or without .json extension)
model_names (required, array): Array of model names to calculate metrics for
metric_definitions (required, array): Array of metric definition objects:
id (optional, string)
name (optional, string)
column (optional, string)
function (optional, enum): "sum", "average", "peak", "min", "cost", "sumIf", "averageIf", "countIf"
comparator (optional, string): For conditional metrics (">=", "<=", ">", "<", "=")
threshold (optional, number): For conditional metrics
time_range (optional, object): Time range filter
start (optional, number): Start timestep
end (optional, number): End timestep
tariff_file_path (optional, string): Path to tariff CSV (required for cost metrics)
tariff_column_index (optional, number): Zero-based index of tariff column (required for cost metrics)
Tool use outside MCP clients
For normal use, call these tools through an MCP client such as Cursor or Claude. Direct HTTP use is mainly for advanced testing or custom integrations.