cloudcompare-mcp (cave / 3D survey fork)

Model Context Protocol (MCP) server for CloudCompare — lets Claude (Desktop or Code) inspect and process point clouds and meshes in natural language.

Fork of yufeioptimal/cloudcompare-mcp (MIT), fixed and tuned for enclosed 3D surveys such as caves, tunnels and hypogea.

What changed from upstream (v0.2.0 → v0.3.0)

Bugs fixed (CloudCompare command line) — checked against CloudCompare's own ccCommandLineCommands.cpp:

Native tools (no CloudCompare needed):

• 3D density. Upstream reported points / XY bounding-box area — meaningless for a cave, a shaft or any enclosed space. Now: median / mean / p95 nearest-neighbour spacing and surface density (pts/m² of wall, same definition as CloudCompare's), robust to subsampling.

• Large files. LAS/LAZ are streamed in chunks with random sampling, so multi-GB scans don't need to fit in memory. Point count and bounding box come from the header (exact).

• Real intensity colouring (upstream used Z as a "proxy").

• Plan + two elevations at true scale (equal aspect), CRS shown when the LAS has one.

• Blocking work runs off the MCP event loop; long CloudCompare jobs time out after 2 h (CLOUDCOMPARE_TIMEOUT in seconds).

Related MCP server: PointCloud MCP

New in v0.4.0

• cut_ceiling — floor-relative ceiling cut. The plan is split into cells; each vertical column is split at empty gaps and segments alternate floor / ceiling (works with stacked galleries). Cells whose lowest surface is far above the neighbouring floor (occluded floor) are handled. Writes a HeightAboveFloor field. Returns a plan picture plus three check sections (kept / removed).

• extract_sections — cross-sections looking along the centerline (left side negative), true scale.

• register_scans — ICP by CloudCompare, but the transform is applied to the original points with laspy, so all LAS attributes survive; scan_id tells scans apart.

• Fix: multi-file CloudCompare commands (C2C, C2M, ICP, merge) now use one explicit global shift for every file. Before, CloudCompare could re-centre each LAS differently and compute in mismatched frames. ICP matrix is written next to the output, not next to the input.

New in v0.4.1 — register_scans for real-world surveys

• rotation: XYZ (free ICP), Z (only rotation about the vertical, default — levelled TLS/SLAM), NONE (translation only). Georeferenced scans that are merely shifted, or scans with little overlap (< 20 %), need NONE: a free ICP slides along straight passages.

• engine: cloudcompare (CloudCompare -ICP with -ROT) or native (robust trimmed translation-only ICP, no CloudCompare needed).

• mode: all_previous (default — each scan aligned onto everything already aligned, best for networks of galleries), chain, reference.

• Safety check: a result that moves a scan more than max_shift (2 m) or rotates it more than max_rotation_deg (5°) is rejected and the scan left in place, with a warning.

• Contact statistics before/after for every scan (points within 15 cm of the model and their median gap).

v0.4.2: the merged file keeps the coordinate system of the reference scan (GeoTIFF keys / WKT copied without pyproj), and register_scans also writes <output>_scansioni.geojson (footprint of every scan with its correction and contact before/after, ready for QGIS) and <output>_report.json.

Tested on four georeferenced scans of the Leros hospital tunnels (2.7 M points, 5–12 % overlap): a free ICP slid by ~10 m; translation-only aligned them (vertical offsets of 10–48 cm), contact at junctions doubled and the median gap dropped from ~8 to ~5 cm.

Tools

All CloudCompare tools work on files in batch (CloudCompare's command-line mode). They do not drive an open CloudCompare window.

Install

Requirements: Python ≥ 3.10, uv (recommended), CloudCompare ≥ 2.12 for the CloudCompare tools.

Claude Desktop

Settings → Developer → Edit config, then add to claude_desktop_config.json:

{
  "mcpServers": {
    "cloudcompare": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Stratos915/cloudcompare-mcp", "cloudcompare-mcp"]
    }
  }
}

Restart Claude Desktop. If CloudCompare is not in a standard location, add:

      "env": { "CLOUDCOMPARE_PATH": "C:\\Program Files\\CloudCompare\\CloudCompare.exe" }

On macOS Claude Desktop may not see uvx on its PATH; use the full path (which uvx, e.g. /Users/you/.local/bin/uvx).

Claude Code

claude mcp add cloudcompare -- uvx --from git+https://github.com/Stratos915/cloudcompare-mcp cloudcompare-mcp

CloudCompare search order

1. CLOUDCOMPARE_PATH

2. cloudcompare / CloudCompare on PATH

3. Windows C:\Program Files\CloudCompare\CloudCompare.exe · macOS /Applications/CloudCompare.app/Contents/MacOS/CloudCompare · Linux /usr/bin/cloudcompare, /snap/bin/cloudcompare

Examples

• "Show me D:\Rilievi\grotta.laz coloured by intensity and tell me the point spacing."

• "Subsample it to 2 cm and remove noise with SOR, save as grotta_2cm.laz."

• "Compare the 2026 survey with the 2024 one (reference) and keep only points that moved more than 5 cm."

Testing status

Tested on macOS (Apple Silicon) with CloudCompare 2.14 on a real TLS cave survey (555k points, UTM coordinates): SOR, spatial subsampling, global shift, ceiling cut and sections. register_scans transform and merge are verified against a known misalignment (error < 0.2 mm); the ICP step uses CloudCompare's own -ICP. Native density statistics are checked on synthetic tunnels.

License

MIT — original work © yufeioptimal; modifications © Stratos915.