Vulcan MCP
This MCP server lets AI agents inspect and control a live Maptek Vulcan 12 project through natural-language-driven tools.
Check Vulcan connectivity, project file inventory, and available Python SDK modules.
Inspect and query block models, including XYZ queries and grade-tonnage statistics with cutoffs.
Analyze triangulations and surfaces: elevation, point-in-solid, volume, centroid, and load/unload.
Work with CAD design databases and layers, load/clear 3D layers, and create polylines or polygons.
Explore drillhole databases, inspect holes/schemas, find high-grade intercepts, and display 3D drillholes.
Inspect, update, and restore Envisage color legends with backups.
Capture the 3D viewport as a JPEG screenshot for multimodal AI vision.
Run Vulcan Workbench macros and print messages to the report window.
Execute custom Python/PyVulcan code directly inside the active Vulcan session.
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., "@Vulcan MCP What's the average gold grade in my block model above a 0.5 cutoff?"
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.
Connect **Vulcan 12 ** directly to Artificial Intelligence assistants (Google Antigravity, Claude Desktop, Claude Code, Cursor, VS Code) via the open Model Context Protocol (MCP) standard.
Seamlessly query block models (.bmf), audit 3D triangulations and solids (.00t), explore ISIS drillhole databases (.dhd.isis), interact with CAD design layers (.dgd.isis), inspect color legends (.scd), capture the Envisage 3D viewport, and execute native PyVulcan automation scripts using natural language.
Key Capabilities
Related MCP server: 3dsmax-mcp
Communication Architecture
Maptek Vulcan 12 Desktop embeds Python 3.5.2 tightly linked to its C++/SWIG graphics engine (maptek.vulcan). Modern MCP servers require Python 3.11+.
The system bridges both worlds across two processes using a local TCP loopback socket on 127.0.0.1:9877:
flowchart LR
A["AI Agent<br/>(Claude / Cursor / Antigravity)"] <-->|"MCP (Stdio)<br/>uvx luiccian-vulcan-mcp"| B["MCP Server<br/>(src/vulcan_mcp)"]
B <-->|"TCP 127.0.0.1:9877<br/>uint32 framing + JSON"| C["Vulcan Listener<br/>(vulcan_listener/server.py)"]
C <-->|"C++ / SWIG Bindings"| D["Maptek Vulcan 12 Desktop<br/>(maptek.vulcan & vulcan_gui)"]Quick Start (in 2 Steps)
You don't need to manually create or configure virtual environments if you have uv / uvx installed.
Strict Execution Order:
STEP 1 (Always First): Start the socket listener inside Maptek Vulcan 12 Desktop. This opens and binds local TCP port
127.0.0.1:9877.STEP 2 (Afterwards): Connect your AI Client (Claude Desktop, Cursor, Antigravity, VS Code).
⚠️ Connecting your AI assistant before starting the listener in Vulcan will result in a ConnectionError.
Step 1: Start the Socket Listener inside Maptek Vulcan 12
Open your mining project in Maptek Vulcan 12 Desktop (Envisage).
In Vulcan's top menu, go to File > Python Script (or type
pyin Vulcan's command window).Select the file
vulcan_listener/server.py.Check the box "Run in shell window" and click OK.
A Windows console window will open confirming the listener is running:
==============================================================
[Vulcan MCP] Vulcan MCP Listener started on 127.0.0.1:9877
[Vulcan MCP] Working directory: C:\your_mining_project
[Vulcan MCP] Registered domains: block_model, canvas, design, drillholes, execute_code, legend, system, triangulation
[Vulcan MCP] Token authentication: DISABLED (localhost open mode)
[Vulcan MCP] Keep this window open while using your AI client. Ctrl+C to stop.
==============================================================Keep this console window open while chatting with your AI assistant. If closed, the TCP socket will terminate.
Step 2: Connect your AI Client
Choose the mode that best fits your workflow:
Mode A: For End Users (Zero-Install via uvx)
No repository cloning required. The AI client pulls and runs the MCP server on the fly:
In Claude Desktop / Cursor / VS Code: Add this block to your MCP config file (
claude_desktop_config.json,.cursor/mcp.json, etc.):{ "mcpServers": { "vulcan": { "command": "uvx", "args": [ "luiccian-vulcan-mcp" ] } } }TIPDynamic Port Configuration: Port
9877is used by default. If9877is already in use or you are running multiple Vulcan sessions, define a custom port via"env"without touching code:"env": { "VULCAN_MCP_PORT": "9878" }In Claude Code (CLI):
claude mcp add -s user vulcan -- uvx luiccian-vulcan-mcp
Mode B: For Developers (with uv run on a local clone)
If you are developing or modifying the codebase and want hot-reloading:
Manual Local Configuration: To connect directly to your local clone:
{ "mcpServers": { "vulcan": { "command": "uv", "args": [ "run", "--directory", "C:\\path\\to\\vulcan-mcp", "vulcan-mcp-server" ] } } }
The 9 Master Tools Catalog
See complete parameter specifications and JSON schemas in docs/MCP_TOOLS_REFERENCE.md.
# | MCP Tool | Mining Domain | Actions ( | Description |
1 |
| System & Project |
| Connection health, complete active project file inventory, and available SDK modules. |
2 |
| Block Models ( |
| Block model schema, $(X,Y,Z)$ point query, tonnage, volume, and volume-weighted mean grade with cutoffs. |
3 |
| Triangulations ( |
| Nodes, faces, volume, topological consistency, centroid, $Z$ elevation, and point-in-solid test. |
4 |
| 3D CAD Design ( |
| CAD layer inspection, planar area ($m^2$), centroid, 3D layer loading, and polyline creation. |
5 |
| ISIS Drillholes ( |
| Drillhole database exploration, high-grade intercept search, and desurveyed 3D colored display. |
6 |
| Legends ( |
| Color scheme inspection and interval color updates with automatic |
7 |
| Visual 3D Viewport | (Direct: | Viewport screenshot of Envisage compressed as JPEG for multimodal vision analysis. |
8 |
| UI & Macros |
| Envisage Workbench macro execution and writing messages to Vulcan's report window. |
9 |
| PyVulcan Scripting | (Direct: | Direct execution of Python scripts inside Maptek Vulcan ( |
Practical & Simple Examples
Here are 4 representative mining workflows demonstrating the natural language user prompt, the resulting MCP tool call in JSON, and the returned data.
1. Project Health Diagnostic & File Inventory
Natural Language Prompt:
"What mining files and block models are available in the open Vulcan project?"
MCP Tool Call:
{ "tool": "vulcan_system", "arguments": { "action": "project_info" } }Returned Response:
{ "connected": true, "project_dir": "C:\\MiningProjects\\Deposit_Cu_Au", "inventory": { "block_models": { "count": 2, "files": ["global_deposit.bmf", "phase1.bmf"] }, "triangulations": { "count": 4, "files": ["topo_2026.00t", "final_pit.00t"] }, "drillhole_dbs": { "count": 1, "files": ["rc_drilling.dhd.isis"] } } }
2. Mineral Resource Estimation with Cutoff Grade
Natural Language Prompt:
"Calculate the tonnage and mean copper grade (CUT) in 'phase1.bmf' using a cutoff >= 0.40% and density of 2.7 t/m³."
MCP Tool Call:
{ "tool": "vulcan_block_model", "arguments": { "action": "stats", "name": "phase1.bmf", "variable": "CUT", "cutoff": 0.40, "default_density": 2.7 } }Returned Response:
{ "total_blocks": 120500, "blocks_above_cutoff": 35210, "total_volume": 2816800.0, "tonnage": 7605360.0, "mean_grade": 0.785, "variable": "CUT", "cutoff": 0.4 }
3. High-Grade Intercept Detection & 3D Display
Natural Language Prompt:
"Find the top 5 gold intercepts in the ASSAYS table of 'rc_drilling.dhd.isis' and display them in Envisage."
MCP Tool Call:
{ "tool": "vulcan_drillholes", "arguments": { "action": "high_grade", "name": "rc_drilling.dhd.isis", "table": "ASSAYS", "field": "AU", "top_n": 5 } }Returned Response:
{ "database": "rc_drilling.dhd.isis", "table": "ASSAYS", "field": "AU", "intercepts": [ { "hole_id": "RC-104", "from": 84.0, "to": 88.0, "grade": 12.45, "length": 4.0 }, { "hole_id": "RC-112", "from": 120.0, "to": 126.0, "grade": 8.70, "length": 6.0 } ] }
Graphics Safeguard: When using the display action to render drillhole intervals in Envisage, keep the limit parameter moderate ($\le 300$) to prevent freezing the OpenGL graphics thread.
4. Direct Automation with PyVulcan Scripting
Natural Language Prompt:
"Run a script inside Vulcan that reports the active window title in the report console."
MCP Tool Call:
{ "tool": "vulcan_execute_code", "arguments": { "code": "import maptek.vulcan_gui as vg\nresult = {'window_name': vg.get_window_name() if hasattr(vg, 'get_window_name') else 'Envisage'}" } }Returned Response:
{ "success": true, "result": { "window_name": "Envisage - [C:\\MiningProjects\\Deposit_Cu_Au]" } }
Configuration & Environment Variables
Both the plugin inside Maptek Vulcan and the external MCP server automatically read operating system environment variables (os.environ):
Variable | Default | Type | Description | When is it used? |
|
| String | IP address where the plugin listens and the MCP server connects. | Optional. Change if running Vulcan on a separate VM or container. |
|
| Integer | TCP port for binary | Optional. Change if port 9877 is used by another application. |
|
| String | Shared secret authenticated via constant-time HMAC. | Required if |
Authentication & Security
Zero .env Philosophy
You do not need to create or manage insecure .env files containing plain text passwords that might accidentally be committed to Git. Tokens are managed at the Windows OS environment level:
# 1. Generate and save a token permanently in your Windows user account:
$token = python -c "import secrets; print(secrets.token_urlsafe(32))"
[System.Environment]::SetEnvironmentVariable('VULCAN_MCP_TOKEN', $token, 'User')
# 2. Verify that it was stored correctly:
[System.Environment]::GetEnvironmentVariable('VULCAN_MCP_TOKEN', 'User')
# 3. (Optional) To revoke and revert to open mode:
[System.Environment]::SetEnvironmentVariable('VULCAN_MCP_TOKEN', $null, 'User')Strict Non-Loopback Network Rule
If you bind
VULCAN_MCP_HOSTto a non-loopback interface (e.g.,0.0.0.0or a LAN IP), the plugin strictly refuses to start (RuntimeError) unlessVULCAN_MCP_TOKENis set, preventing unauthorized remote script execution.
🛠️ Diagnostics & FAQ
Is the assistant hanging on Timeout or not responding?
Maptek Vulcan Desktop is an interactive MFC/C++ application. When an operation triggers a modal dialog popup (e.g. file overwrite confirmation, coordinate system prompt), Vulcan's main Python thread is completely suspended until a human clicks OK or Cancel in Vulcan. As soon as the modal is dismissed, processing resumes instantly. See How to Resolve Modal Dialog Freezes.
3-Layer Automated Testing Harness
The project includes automated testing infrastructure organized across 3 validation tiers:
🤝 Contributing
Contributions, bug reports, and suggestions are warmly welcomed! Please read our Contributing Guide (CONTRIBUTING.md) to learn about:
Setting up the local development environment with
uv.Feature branch workflows (
feat/*,fix/*) to keepmasterstable.Strict Python 3.5.2 compatibility in
vulcan_listener/(no f-strings).Release automation and synchronized version bumping (
scripts/bump_version.py).Conventional Commits and submitting Pull Requests with GitHub CLI (
gh).
Available Tools
9 toolsvulcan_block_modelVulcan Block Model Operations (.bmf)ARead-only
Master tool for inspecting and querying Vulcan block models (.bmf).
Actions:
list: List all .bmf files in the project.
info: Get block model origin, extent, block sizes, total blocks, and variable definitions (requires
model).query_xyz: Read block grades/attributes at world coordinates (
model,x,y,z, optionalvariables).stats: Compute grade-tonnage statistics, volume-weighted mean, and cutoff summary (
model,variable, optionalcutoff,density,select).
Inputs: action (required), x, y, z, +6 more.
vulcan_canvasVulcan GUI & Report WindowC
Run a Vulcan Workbench macro command or print a message to Vulcan's Report Window.
Inputs: action (required), text, macro.
vulcan_designVulcan CAD Design Databases (.dgd.isis)A
Master tool for Vulcan Design Databases (.dgd.isis), layers, and 3D CAD polylines.
Actions:
list_dbs: List all .dgd.isis databases in the project.
list_layers: List all layers and object counts inside a DGD (
dgd).layer_info: Inspect objects inside a layer with pagination (
dgd,layer, optionallimit,offset).load_layer: Render a design layer onto the 3D screen (
dgd,layer, optionaluse_temp_objects,load_method).clear_temp: Remove temporary CAD objects displayed on the 3D screen.
create_polyline: Create a 3D polyline or closed polygon in a layer (
dgd,layer,points, optionalclosed,colour,name).
Inputs: action (required), dgd, name, layer, +7 more.
vulcan_drillholesVulcan Drillhole Databases (.dhd.isis) & 3D DisplayA
Master tool for ISIS Drillhole Databases (.dhd.isis): collars, surveys, assays, lithology, and 3D display.
Actions:
list_dbs: List all drillhole databases in the project.
schema: Return tables (e.g. COLLARES, DIRECCIONES, LEYES, LITOLOGIA), fields, string_fields, and total hole count (
db).holes: Paginated list of drillhole IDs (
db, optionallimit,offset).hole: Get collar, survey, assay, and lithology records for a single hole (
db,hole, optionaltable).high_grade: Scan an interval table for the highest-grade intercepts (
db,table,field,min_value,limit).display: Render 3D drillholes in Vulcan's 3D viewport colour-coded by grade (
db, optionalholes,table,field,limit,max_segments,mode,save_layer).clear_display: Remove rendered 3D drillholes from Vulcan's 3D viewport.
Inputs: action (required), db, hole, mode, +8 more.
vulcan_execute_codeExecute Python Code in VulcanADestructive
Execute custom Python code inside Vulcan's active session (vulcan and vulcan_gui preloaded).
Assign to result inside your snippet to return structured JSON values alongside stdout/stderr.
Inputs: code (required).
vulcan_legendVulcan Envisage Colour Legends (.scd)A
Master tool for reading and updating Maptek Envisage colour legends (.scd).
Actions:
list: List .scd legend files and available colour presets.
inspect: Parse all schemes (BLOCK_COLOUR, DRILL_COLOUR, SAMPLES_COLOUR) in a legend (
scd).update: Update interval colours of a legend table (
scd,scheme,table, andpresetorcolours). Automatically creates a.scd.bakbackup.restore: Restore a legend from its
.scd.bakbackup (scd).
Inputs: action (required), scd, table, preset, +2 more.
vulcan_screenshotVulcan Viewport Screenshot (Token-Optimised)ARead-only
Capture the Maptek Vulcan 3D window as a compressed JPEG image.
Downscales to max_width (default 800px) and encodes as JPEG (quality=70)
to minimise token consumption while preserving clear visual context of the 3D scene.
Inputs: quality, max_width.
vulcan_systemVulcan System & Project InventoryARead-only
Master tool for Vulcan connectivity, active mine project inventory, and SDK capabilities.
Actions:
ping: Check live connection to Maptek Vulcan Desktop.
project_info: List all block models (.bmf), triangulations (.00t/.tri), design DBs (.dgd.isis), drillhole DBs (.dhd.isis), specifications (.dsf), and legends (.scd) in the active project.
capabilities: Inspect available Python modules inside Vulcan (pandas, PIL, win32gui).
Inputs: action.
vulcan_triangulationVulcan Triangulations & Surfaces (.00t / .tri)AIdempotent
Master tool for 3D triangulations, topography surfaces, and pit shells (.00t / .tri).
Actions:
list: List all triangulation files in the project.
info: Return node count, face count, 3D bounding box extent, closure/consistency/crossing state, centroid, and volume (
name).elevation: Query surface Z elevation at [[x, y], ...] coordinates (
name,points).point_inside: Check whether 3D coordinates [[x, y, z], ...] lie inside a closed triangulation solid (
name,points).load: Display triangulation on Vulcan's 3D graphics screen (
name).unload: Remove triangulation from Vulcan's 3D graphics screen (
name).
Inputs: action (required), name, points.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each master tool targets a clearly distinct Vulcan domain: system, block models, triangulations, design DBs, drillholes, legends, screenshots, canvas commands, and Python execution. The main ambiguity is between vulcan_canvas (Workbench macro/Report Window) and vulcan_execute_code (custom Python), which could be confused by an agent choosing how to execute arbitrary logic.
All tool names follow a consistent vulcan_ prefix plus a clear domain noun: vulcan_system, vulcan_block_model, vulcan_triangulation, etc. Snake_case is used consistently throughout, and the action names inside the master tools are also predictable.
Nine master tools is a well-scoped surface for a complex mining-software integration. The master-tool pattern groups many related actions under coherent domains rather than exposing dozens of flattened tools, keeping the top-level count manageable.
The surface covers connectivity, project inventory, block-model querying/statistics, triangulation inspection/display, design DB layers and polylines, drillhole inspection/display, legends, screenshots, and code/macro execution. Minor lifecycle gaps remain, such as block-model or triangulation editing/export operations, but core read/query/display workflows are well covered.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables AI agents to control Ansys Electronics Desktop (HFSS, Maxwell, Q3D, etc.) using MCP tools for simulation automation.10061PolyForm Noncommercial 1.0.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to connect to Autodesk 3ds Max via the Model Context Protocol, allowing natural-language control of scene creation, modeling, materials, viewport capture, and plugin introspection through dedicated MCP tools.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to procedurally generate, transform, inspect, and export 3D meshes and scenes through MCP tools.1MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants like Claude Desktop or Cursor to control supported CAD applications through MCP tools for drawing, layer, block, entity, data export, and file/session operations using natural language or direct tool calls.-