Skip to main content
Glama
Vulcan MCP

Vulcan MCP

by LuiccianDev

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.

IMPORTANT

Strict Execution Order:

  1. 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.

  2. 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

  1. Open your mining project in Maptek Vulcan 12 Desktop (Envisage).

  2. In Vulcan's top menu, go to File > Python Script (or type py in Vulcan's command window).

  3. Select the file vulcan_listener/server.py.

  4. Check the box "Run in shell window" and click OK.

  5. 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.
==============================================================
TIP

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"
          ]
        }
      }
    }
    TIP

    Dynamic Port Configuration: Port 9877 is used by default. If 9877 is 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 (action=)

Description

1

vulcan_system

System & Project

ping, project_info, capabilities

Connection health, complete active project file inventory, and available SDK modules.

2

vulcan_block_model

Block Models (.bmf)

list, info, query_xyz, stats

Block model schema, $(X,Y,Z)$ point query, tonnage, volume, and volume-weighted mean grade with cutoffs.

3

vulcan_triangulation

Triangulations (.00t/.tri)

list, info, elevation, point_inside, load, unload

Nodes, faces, volume, topological consistency, centroid, $Z$ elevation, and point-in-solid test.

4

vulcan_design

3D CAD Design (.dgd.isis)

list_dbs, list_layers, layer_info, load_layer, clear_temp, create_polyline

CAD layer inspection, planar area ($m^2$), centroid, 3D layer loading, and polyline creation.

5

vulcan_drillholes

ISIS Drillholes (.dhd.isis)

list_dbs, schema, holes, hole, high_grade, display, clear_display

Drillhole database exploration, high-grade intercept search, and desurveyed 3D colored display.

6

vulcan_legend

Legends (.scd)

list, inspect, update, restore

Color scheme inspection and interval color updates with automatic .scd.bak backup.

7

vulcan_screenshot

Visual 3D Viewport

(Direct: max_width, quality)

Viewport screenshot of Envisage compressed as JPEG for multimodal vision analysis.

8

vulcan_canvas

UI & Macros

macro, report

Envisage Workbench macro execution and writing messages to Vulcan's report window.

9

vulcan_execute_code

PyVulcan Scripting

(Direct: code)

Direct execution of Python scripts inside Maptek Vulcan (vulcan, vulcan_gui, project_dir).


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 }
      ]
    }
WARNING

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?

VULCAN_MCP_HOST

127.0.0.1

String

IP address where the plugin listens and the MCP server connects.

Optional. Change if running Vulcan on a separate VM or container.

VULCAN_MCP_PORT

9877

Integer

TCP port for binary uint32 message transport.

Optional. Change if port 9877 is used by another application.

VULCAN_MCP_TOKEN

"" (Disabled)

String

Shared secret authenticated via constant-time HMAC.

Required if VULCAN_MCP_HOST is non-loopback (!= 127.0.0.1). Optional on localhost.


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_HOST to a non-loopback interface (e.g., 0.0.0.0 or a LAN IP), the plugin strictly refuses to start (RuntimeError) unless VULCAN_MCP_TOKEN is set, preventing unauthorized remote script execution.


🛠️ Diagnostics & FAQ

NOTE

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 keep master stable.

  • 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 tools
vulcan_block_modelVulcan Block Model Operations (.bmf)A
Read-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, optional variables).

  • stats: Compute grade-tonnage statistics, volume-weighted mean, and cutoff summary (model, variable, optional cutoff, 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, optional limit, offset).

  • load_layer: Render a design layer onto the 3D screen (dgd, layer, optional use_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, optional closed, 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, optional limit, offset).

  • hole: Get collar, survey, assay, and lithology records for a single hole (db, hole, optional table).

  • 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, optional holes, 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 VulcanA
Destructive

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, and preset or colours). Automatically creates a .scd.bak backup.

  • restore: Restore a legend from its .scd.bak backup (scd).

Inputs: action (required), scd, table, preset, +2 more.

vulcan_screenshotVulcan Viewport Screenshot (Token-Optimised)A
Read-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 InventoryA
Read-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)A
Idempotent

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

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -