Inspect, compare, and export point clouds, meshes, and calibrated depth data with inline 3D previews.
Also known as kleinicke/ply-visualizer, 3d-visualizer
- Stars
- 23
- Tools
- 27
- Downloads, 30 days
- 151
- Latest version
- 0.4.2
- Last commit
- Oct 30, 2026
- License
- MIT
What is 3D Visualizer MCP?
3D Visualizer is an MCP server. Inspect, compare, and export point clouds, meshes, and calibrated depth data with inline 3D previews. It exposes 27 tools, such as open_3d_files, open_depth_image, visualize_points.
Summary generated from the project's README
About 3D Visualizer MCP server
Inspecting point clouds, meshes, and calibrated depth data from within an AI conversation or a Python environment is what 3D Visualizer enables. This tool allows developers to visualize 3D geometry through inline previews, making it ideal for researchers monitoring machine learning training or engineers analyzing spatial data. It supports various data formats including NumPy arrays and PyTorch tensors, handling both CPU and GPU inputs without requiring manual data conversion.
Users can set up the server locally using uv to install the package with mcp and headless extras. The configuration requires specifying a root directory for data access. Depending on the needs, the renderer can be set to auto, inline, or headless mode, with the latter requiring Chromium for unattended work. The server provides a core set of eight tools by default, but a full toolset is available for advanced tasks like depth conversion, animation, alignment, and exporting data.
What you can do with it
- 1Monitor machine learning trainingAn AI client can visualize how point cloud predictions evolve during a training loop by receiving periodic updates.
- 2Inspect model gradientsDevelopers can visualize gradient descent directions by anchoring magenta arrows to specific input points.
- 3Analyze training batchesUsers can switch between different samples in a batch within a single scene to inspect augmentations.
- 4Automated data inspectionRun headless rendering tasks to capture 3D scene snapshots as images without a visible browser window.
Written from the project's README. Every use case is checked against a quote from it.
How to install 3D Visualizer MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall 3D Visualizer MCP in Claude Code
$ claude mcp add 3d-visualizer -- uvx --from '3d-visualizer[mcp]' 3d-visualizer mcp --root /path/to/folderInstall 3D Visualizer MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"3d-visualizer": {
"command": "uvx",
"args": [
"--from",
"3d-visualizer[mcp]",
"3d-visualizer",
"mcp",
"--root",
"/path/to/folder"
]
}
}
}Install 3D Visualizer MCP in VS Code
.vscode/mcp.json
{
"servers": {
"3d-visualizer": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"3d-visualizer[mcp]",
"3d-visualizer",
"mcp",
"--root",
"/path/to/folder"
]
}
}
}Install 3D Visualizer MCP in VS Code CLI
$ code --add-mcp '{"name":"3d-visualizer","type":"stdio","command":"uvx","args":["--from","3d-visualizer[mcp]","3d-visualizer","mcp","--root","/path/to/folder"]}'Install 3D Visualizer MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"3d-visualizer": {
"command": "uvx",
"args": [
"--from",
"3d-visualizer[mcp]",
"3d-visualizer",
"mcp",
"--root",
"/path/to/folder"
]
}
}
}Install 3D Visualizer MCP in Codex
$ codex mcp add 3d-visualizer -- uvx --from '3d-visualizer[mcp]' 3d-visualizer mcp --root /path/to/folderInstall 3D Visualizer MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.3d-visualizer] command = "uvx" args = ["--from", "3d-visualizer[mcp]", "3d-visualizer", "mcp", "--root", "/path/to/folder"]
Install 3D Visualizer MCP in Gemini CLI
$ gemini mcp add -s user 3d-visualizer uvx -- --from '3d-visualizer[mcp]' 3d-visualizer mcp --root /path/to/folderInstall 3D Visualizer MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"3d-visualizer": {
"command": "uvx",
"args": [
"--from",
"3d-visualizer[mcp]",
"3d-visualizer",
"mcp",
"--root",
"/path/to/folder"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for 3d-visualizer 0.4.2 in an isolated container with no network and no keys. It answered and listed 27 tools.
3D Visualizer MCP tools 27
Read from the server with tools/listopen_3d_filesActionOpen local point clouds/meshes/splats/animated models together. Pass scene_id to append while preserving camera and existing objects. Include explicit supporting .bin/textures for GLTF/DAE/FBX; no implicit disk or network reads. Paths must be under configured roots. Returns a persistent scene_id and local URL; inspect to verify loading.
open_depth_imageActionProject a depth/disparity raster inline using explicit calibration from surrounding files/context. Read viewer://depth-calibration for coefficient ordering and encoding. Calibration dimensions must match the raster; no parameter guessing. Supports NPY/NPZ, TIFF, PNG8/16, EXR, PFM and COLMAP dense .bin. Optional aligned RGB (HxWx3, 0..255), confidence and mask files. Pass scene_id to append without moving the camera. For a COLMAP dense workspace, set path=workspace and colmap_image=exact image name; calibration comes from its undistorted sparse model. Inspect after loading for pixel counts, provenance and projection diagnostics; picks/exports retain original pixel coordinates and raw values.
visualize_pointsActionVisualize up to 20,000 XYZ points, optional RGB (integer 0..255), target overlay, or anchored vector arrows. Use files for larger data; coordinates are not automatically normalized.
open_3d_urlActionDownload one URL or a list of direct HTTP(S) 3D files into one scene; pass scene_id to append. Self-contained models recommended; external resources are not fetched implicitly. Download each file on the local MCP server and open it inline. This makes a network request to the supplied URL and redirects; no browser CORS is needed. Supports the same formats as local files plus gzip. Supply filename for extensionless/signed URLs. Defaults to a 256 MiB transfer/decompressed limit, at most 1 GiB; 30-second socket and 120-second transfer limits. No login/cookies or webpage extraction. Temporary files are deleted when the scene closes.
update_3d_sceneActionReplace the existing scene's geometry while preserving its camera. Omitted overlays/vectors are removed. Reuses the active inline viewer or explicit browser fallback.
list_3d_scenesRead-onlyList scenes owned by this MCP process and their local viewer URLs.
inspect_3d_sceneRead-onlyInspect loaded geometry and build IDs (Python package/server and actual renderer; renderer_matches_bundle detects an old widget). Read coordinate conventions/units, camera position/direction/rotation center, projection and viewport, object transforms, opacity/color, exposure/background, selection criteria, geometry counts and bounds from the active inline viewer or explicit browser fallback. Times out if no renderer responds. Compare rendered_revision with the submitted revision.
set_3d_cameraActionPartially update camera position, target (rotation center), up or vertical FOV in degrees. Rotation is absolute XYZ Euler degrees; it moves target along camera -Z at the previous pivot distance. Rotation cannot combine with target/up. Fit frames visible geometry, optionally at the new FOV. Returns applied view state.
capture_3d_viewRead-onlyReturn an actual PNG of the rendered 3D canvas (maximum 1024 pixels per side) so the agent can visually inspect the result. Requires an active inline viewer or explicit browser fallback.
close_3d_sceneActionRelease a viewer's local server and temporary data. Does not delete the user's source files. Any active viewer disconnects.
navigate_3d_viewActionNavigate without UI. Fit tightly; presets use Y-up OpenGL. Orbit angles are degrees. Pan/pivot use world XYZ. Zoom <1 moves closer. Pick uses normalized canvas XY (top-left=0,0) and sets rotation center on visible geometry, like double-click. Origin resets pivot to 0,0,0.
set_3d_appearanceActionSet exposure stops, background #RRGGBB, persistent pivot axes, coordinate grid, object/color legend and UI theme. gamma_correction matches the UI toggle: true treats source RGB as linear (extra gamma appearance); false decodes sRGB before shading. Enabled grid/legend are also included in agent PNG captures. Axes may briefly appear during interaction when persistent axes are off.
Show all 27 toolsShow fewer tools
set_3d_objectActionSet overlay opacity (0..1), visibility, world-unit point size (or point_size_mode=adaptive for a camera-dependent 2/4/8 pixel target; point_size_pixels=1..64 explicitly sets that target and enables adaptive sizing), points/mesh representation, fixed RGB color or original/intensity/scalar coloring. Get object_index, scalar_fields and available_color_modes from inspection; these include palette indices and projected colors when available. Mesh requires faces. Fixed color and color_mode are mutually exclusive.
transform_3d_objectActionTransform one cloud/mesh without changing source files or camera. Translate/scale use vector XYZ; rotate uses vector axis plus angle degrees (90 for quarter turns); quaternion uses XYZW, normalized. Matrix is affine 4x4 COLUMN-MAJOR, matching inspection (transpose row-major UI input). Default composes current*delta in local space; world uses delta*current. pivot=center rotates/scales around the current bounding-box center; explicit XYZ pivot uses the chosen space; omitted pivot is the coordinate origin. Undo restores the last of up to 50 agent edits per object. replace=True sets an absolute transform. Invert/reset act on the current matrix. Inspect local_to_world to verify. Visibility, point size and coloring use set_3d_object.
measure_3d_sceneActionAdd/list/clear visible measurements in scene units. Distance uses start/end XYZ; path_point appends end to the active path; undo removes its last point; close_path toggles closure.
control_3d_videoActionControl camera keyframes, or model animation when object_index is supplied. Model: list clips, update(index/speed), play, stop (pause), loop(enabled), goto(time in seconds, pauses). GLB/GLTF/FBX/DAE retain supported embedded animation; 3DS is static. With no object_index, manage camera keyframes: Add captures current camera. Update sets segment duration/dwell in seconds. Loop requires enabled; play needs two keyframes; stop restores camera. Returns reusable keyframe poses.
align_3d_cloudsActionStart a registration job, then poll action=status until job.state is completed/failed; submitted is not aligned. Reuses the viewer's Rust solvers. auto: level/up-axis yaw sweep then ICP; icp: refine an already close pair; correspondences: fit >=3 non-collinear paired world XYZ landmarks. source_index moves, target_index stays fixed. align_all/refine_all hold target fixed; strategies anchor (each to anchor), nested (grow aligned union), complex (grow with extra hypotheses). For auto/icp, against_all_others matches the moving cloud to the union of all other clouds. No scale/nonrigid estimation. up_axis describes the DATA, not the camera (default y); use z for Z-up scans. Clear temporary selections first. Undo restores transforms from the last accepted agent job. Inspection/capture remain available; geometry refresh waits for alignment. Partial align-all failures are reported per object.
pick_3d_pointRead-onlyPick normalized canvas XY without moving the camera. Returns hit/miss, world XYZ, object and decoded point indices and scalar attributes. Mesh/splat picks may have null indices; never infer object identity from those.
manage_3d_viewsActionSave/restore named camera views for this renderer session; undo the last agent camera change (up to 50). Names are not persisted after closing/reloading the widget. Does not restore geometry or filters.
select_3d_regionActionOne-step select/isolate/focus with PNG preview. Select all points in an object, or intersect scalar field values, world box [minX,minY,minZ,maxX,maxY,maxZ], and plane halfspace ax+by+cz+d>=0. Creates a reversible highlighted point subset; clear restores prior visibility. Label IDs are numeric, not semantic object names: inspect attributes/pick first. No automatic segmentation; point clouds only. Replaces the previous selection. Disable highlight to preserve original colors. Moving the plane requires another select call.
manage_3d_selectionsActionName the active selection; retain up to 20 independent subsets. Toggle each name's visibility or activate/focus it. Union/intersection/subtract combine two names from the same source into a new active selection; save it to retain it. Defaults isolate=False and focus=False preserve existing visibility and camera. Empty set results return status=empty, clear the active selection, and cannot export the previous result. Geometry updates expire selections; scene-state export persists them.
manage_3d_scene_statesActionSave/restore complete camera, transforms, selection/named subsets, visibility, color, opacity and presentation. Export/import a .json under configured roots to persist after restarting. Reopen identical geometry in the same order before import; import stores a state; restore=True imports and applies it in one call. Existing files are never overwritten. Maximum 20 states, 4 MiB each. JSON does not embed geometry or playback. action=export_models writes all visible models as a new .glb (no name required), including supported native animation clips. GLB excludes Gaussian splats, grid/UI, source-row attributes and point-size settings; use subset PLY for analysis attributes. Export limit 256 MiB.
export_3d_selectionActionWrite the active or named subset to a NEW binary .ply under configured roots (maximum 256 MiB). Preserve decoded RGB, normals, scalar attributes, decoded indices, and original source_row when available (depth raster: pixel_v*width+pixel_u). Coordinates are object-local; header stores local_to_world and source origin. Returns a path, never point data/base64. No overwrite; not a lossless copy of the original file's numeric types.
compare_3d_cloudsActionEnable linked side-by-side WebGL views with the same camera (EDL off in split mode); disable restores ordinary rendering. Distance colors left by world-space distance to right: nearest within max_distance, unmatched=NaN; paired uses corresponding decoded order and requires equal counts. Distance limit: one million combined points. Changes mark distances stale; recompute with action=recompute,left=<source> reuses recorded settings. Restored distance fields require an explicit distance computation. No alignment is run.
preview_3d_viewsRead-onlyReturn one labeled multi-view PNG to choose a useful angle, preserving the original camera. Disable split comparison first. Includes enabled grid, legend and selection summary.
read_viewer_dataRead-onlyApp-only transport: session metadata, pending commands or bounded geometry chunks.
submit_viewer_replyActionApp-only transport: acknowledge a rendered command result.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablekleinicke/ply-visualizer is public and reachablegithub.com/kleinicke/ply-visualizer ↗Pass
- Package names this repository as its source3d-visualizer names kleinicke/ply-visualizer as sourcepypi.org/project/3d-visualizer/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-30github.com/kleinicke/ply-visualizer ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from 3d-visualizerPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model27 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub3D Visualizer — Python, CLI and MCP
Inspect point clouds, meshes and calibrated depth data in Python, notebooks or
an AI conversation. The package is 3d-visualizer, the Python import is
viz3d, and the CLI is 3d-visualizer. Python 3.10+ is required.
This checkout targets the next release. The public 0.4.2 package still uses the
older import. For the new interface before publication, build the viewer and
install ./packages/python with the extras you need.
Agent installation
These examples target 0.5.0.dev0. Development versions must be installed from this checkout until published; do not assume an unreleased version exists on PyPI.
For agents, use uv tool install or uvx; uv add is for using the library
inside a Python project. Headless mode also needs Chromium installed once.
uv tool install "3d-visualizer[mcp,headless]==0.5.0.dev0"
uvx --from "3d-visualizer[headless]==0.5.0.dev0" playwright install chromium
3d-visualizer doctor --check-headless
Client configuration (replace the data directory):
{
"mcpServers": {
"3d-visualizer": {
"command": "uvx",
"args": [
"--from",
"3d-visualizer[mcp,headless]==0.5.0.dev0",
"3d-visualizer-mcp",
"--root",
"/absolute/path/to/data"
]
}
}
}
The VS Code link uses the current workspace as the allowed data root.
claude mcp add --transport stdio 3d-visualizer -- uvx --from "3d-visualizer[mcp,headless]==0.5.0.dev0" 3d-visualizer-mcp --root /absolute/path/to/data
The default --tools core exposes eight everyday tools. Use --tools full
for depth conversion, selections, animation, alignment and export.
--renderer auto uses an advertised MCP Apps host, otherwise offscreen
Chromium. Use --renderer inline to require a widget or explicit browser;
use --renderer headless for unattended work.
Unattended Python rendering
With the headless extra and Chromium installed:
from pathlib import Path
from viz3d import show
with show("scan.ply", headless=True) as view:
state = view.inspect(detail="full")
Path("preview.png").write_bytes(view.capture())
This uses offscreen Chromium and the shared renderer. It requires no notebook, chat widget or visible browser window. Inspect and capture raise on renderer failure instead of returning a placeholder success.
Install with uv (recommended)
Install uv, then choose:
uv add 3d-visualizer # Add to a Python project
uv add "3d-visualizer[notebook]" # Local notebook display support
uv pip install 3d-visualizer # Install into an existing virtual environment
uv tool install 3d-visualizer # Install the CLI independently
uvx --from 3d-visualizer 3d-visualizer scan.ply # Run without persistent installation
The Python import is from viz3d import show. Tool installation does not add
the library to a Python project or notebook kernel; use uv add or
uv pip install in that environment. No Node.js build is needed for PyPI
installs.
For local Jupyter, run uv run --with jupyter jupyter lab from your project and
select its Python kernel. Keep that kernel alive while using the viewer.
Developing from source
From the repository root, build the bundled engine with Node 24:
npm ci
npm run build:python-viewer
uv tool install ./packages/python
# Or add the local library to your Python project:
uv add /absolute/path/to/checkout/packages/python
See publishing setup for releases.
Alternative: install with pip from this repository
After building the browser assets above:
python3 -m venv packages/python/.venv
packages/python/.venv/bin/python -m pip install ./packages/python
packages/python/.venv/bin/3d-visualizer engine/examples/example-point-cloud.ply
On Windows, replace the environment's bin/ paths with Scripts/, e.g.
packages\python\.venv\Scripts\python.exe, 3d-visualizer.exe, or
jupyter.exe. After activating the environment, the command is simply:
3d-visualizer scan.ply mesh.stl
3d-visualizer --no-browser scan.ply
python -m viz3d scan.ply
The command prints a local URL and keeps running until Ctrl+C. --no-browser
allows an agent or another application to open that URL itself. It does not
render an image or report successful browser rendering to the caller.
Python
from viz3d import show
# In an interactive Python session or local notebook:
viewer = show("scan.ply", "mesh.stl")
print(viewer.url)
# Later:
viewer.close()
from viz3d import show
# Lists, iterables, NumPy arrays, and PyTorch tensors with shape (N, 3) work.
points = [[0, 0, 0], [1, 0, 0], [0, 1, 0]]
colors = [[255, 0, 0], [0, 255, 0], [0, 0, 255]]
# In a script, keep Python alive while the viewer is in use.
with show(points, colors=colors) as viewer:
print(viewer.url)
try:
viewer.wait()
except KeyboardInterrupt:
pass
Coordinates must be finite float32-compatible numbers. Optional colors must match the point count and contain integer RGB values in 0..255. Point arrays are serialized to a temporary binary PLY, decoded by the existing engine, and removed when the session closes. This first implementation serializes arrays row by row; it is not a zero-copy transport for very large arrays.
NumPy and PyTorch
Pass arrays and tensors directly, including RGB colors:
import numpy as np
from viz3d import show
viewer = show(np.random.default_rng(0).normal(size=(1000, 3)))
import torch
from viz3d import show
device = "cuda" if torch.cuda.is_available() else (
"mps" if torch.backends.mps.is_available() else "cpu"
)
points = torch.randn(1000, 3, device=device, requires_grad=True)
rgb = torch.randint(0, 256, (1000, 3), device=device, dtype=torch.uint8)
viewer = show(points, colors=rgb)
# No manual .detach(), .cpu(), or .numpy() needed.
# Keep Python alive and call viewer.close() when finished.
- NumPy arrays can be transposed, sliced, read-only, or non-contiguous.
- PyTorch inputs can be CPU or GPU tensors, detached or attached to autograd. Both coordinates and colors are handled independently, so mixing devices or NumPy/PyTorch inputs works. Float16 and bfloat16 tensors are supported.
- Visualization detaches internally, transfers to CPU, and serializes a
snapshot. The original device, values,
requires_grad, and autograd graph are unchanged. GPU-to-CPU transfer synchronizes; avoid calling this every training step. - PyTorch conversion does not depend on NumPy. CPU rows are converted in bounded chunks rather than performing a GPU scalar read for every coordinate.
- Inputs must be real, dense
(N, 3)data. For(B, N, 3)batches, useshow(batch[0]); batches are deliberately not flattened automatically. Sparse, quantized, complex, nested, and data-free meta tensors are rejected with an error. RGB retains the integer-valued 0..255 convention, including floating-point tensors; normalized RGB can be passed as(rgb * 255).round().
Training previews
All updates reuse the same browser tab/inline view and preserve its camera. The viewer receives change notifications and loads the newest revision; intermediate revisions can be skipped. Publish at a useful training interval, not every forward pass. Serialization and GPU transfer are synchronous. Updates replace the scene; manual files added to that scene are also replaced on the next update.
viewer = show(initial_points)
# In your training loop, e.g. every 100 steps:
if step % 100 == 0:
viewer.update(prediction[0], target=target[0], step=step)
Prediction is orange and target cyan. Supply colors= to override prediction
RGB. Targets may have a different number of points. This is a geometric overlay,
not a computed nearest-neighbor error metric. Visibility can be toggled in the
standard file panel. Use Pause updates to inspect one revision and Fit
scene to reset the framing explicitly.
Batch and augmentation inspection
from viz3d import show_batch
viewer = show_batch(batch, target=target_batch)
viewer.update_batch(next_batch, target=next_targets, step=step)
# A list of differently sized point arrays also works:
viewer = show_batch([original, augmented], labels=["Original", "Augmented"])
The sample selector switches batches in one scene and retains the camera. Colors, targets, and vectors (when supplied) must match the batch size. Batch snapshots serialize every sample; select a small inspection subset for large training batches. Only the chosen sample is loaded by the browser.
Gradient and displacement arrows
# After loss.backward(); non-leaf predictions need retain_grad() beforehand.
viewer.update(
points,
vectors=points.grad,
vector_scale=-learning_rate,
max_vectors=256,
step=step,
)
Arrows are anchored at the corresponding input points. Negative learning-rate
scaling shows a plain gradient-descent direction; it is not an exact Adam or
momentum optimizer step. To inspect the actual update, pass measured coordinate
displacements instead. Nonzero arrows are magenta. Up to max_vectors evenly
spaced vectors are displayed (default 256, maximum 2000). All supplied vector
rows are validated; no autograd hooks or gradient computation are installed by
this operation.
Layer inspection with a removable forward hook
viewer = show(initial_points)
with viewer.inspect_layer(model, select=lambda output: output[0], every=100):
train(model)
For dictionary outputs use a selector such as
lambda output: output["points"][0]. The selector must return (N, 3)
coordinates, not arbitrary feature channels. The hook captures the first forward
call and then every every calls. It returns None, preserving the model's
output. A visualization error disables the hook, emits a warning and is
accessible as inspection.error; it does not invalidate training. The context
manager removes the hook, while the caller owns the viewer session's lifetime.
inspection.close() also removes it explicitly.
Run viewer updates in the main process, on one rank in distributed training, and outside compiled model code. GPU-to-CPU transfer introduces synchronization. PyTorch forward hooks.
The server binds only to 127.0.0.1, uses a random session URL, and serves only
the explicitly supplied files and bundled viewer assets. Source files remain on
your machine; the package does not upload them. Keep file paths available for
the life of the session. Do not share the session URL with untrusted code.
Inline Jupyter notebooks
In a local Jupyter notebook, return the viewer as the last expression in a cell. Browser auto-opening is disabled when a notebook kernel is detected:
viewer = show(points)
viewer # Interactive viewer appears in the output cell.
Or display explicitly, using the notebook extra:
viewer.display(height=480, ui="collapsed")
Settings are collapsed by default. A compact toolbar keeps Settings, Fit
scene, Pause updates, and the batch selector accessible. Choose
ui="full" to show settings immediately or ui="none" for a presentation-only
canvas with mouse controls. In UI-free mode, batch selection is unavailable;
choose the sample in Python before displaying it.
viewer.update(...) updates every open view, including notebook output. Keep
the kernel running, call viewer.close() when done, and do not call
viewer.wait() in a cell. Notebook output contains a live local iframe, not an
offline saved scene. Reopen the session after restarting the kernel.
This initial inline transport requires the browser and kernel on the same machine and a notebook host that permits local iframes. Remote Jupyter, Colab, and notebook environments that block local iframe URLs need a widget/proxy transport; they are not supported by this transport yet.
For a mature widget-based alternative, K3D supports notebook point clouds and other 3D primitives. Rerun is worth considering for recorded, time-based diagnostics. This package embeds the existing 3D viewer to retain its file formats and interaction controls.
Current scope
- Supported inputs: PLY, XYZ, XYZN, XYZRGB, PCD, PTS, OBJ, STL, OFF, GLB, LAS/LAZ, E57, SPZ, SPLAT, KSPLAT, and SOG.
- Multiple files appear together in one scene.
- OBJ input currently provides geometry; automatic sidecar material/texture resolution and external-resource glTF are outside this preview.
- No separate image-viewer integration or desktop launch integration yet. The shared 3D viewer retains its existing manual controls and depth-conversion features.
Build a distributable wheel
npm run build:python-viewer
packages/python/.venv/bin/python -m pip wheel --no-deps ./packages/python --wheel-dir /tmp/3d-visualizer-wheels
The wheel includes the browser engine and its assets. Install that wheel on
another machine with python -m pip install /path/to/the.whl; no Node.js or
Tauri installation is necessary there. Build assets before packaging.
Verify
npm run test:python-viewer
# Also test actual NumPy/PyTorch inputs in the isolated environment:
packages/python/.venv/bin/python -m pip install numpy torch
packages/python/.venv/bin/python -m unittest discover -s packages/python/tests -v
cd engine
npx playwright test local-session.spec.ts --reporter=line
The browser test requires npm run build:python-viewer and the existing engine
test server assets in engine/dist (npm run build --workspace=engine). Array
tests skip optional libraries and GPU backends that are unavailable.
Available platforms
- VS Code Marketplace: Install extension
- Open VSX: Install extension
- Website: 3d.f-kleinicke.de
- PyPI (Python and CLI): 3d-visualizer
- JetBrains: Signed preview and installation
- Standalone app: Tauri desktop preview
MCP is supported: agents can open and update 3D scenes, control the camera, and inspect rendered screenshots. See the MCP setup guide.
3D Visualizer MCP questions
How do I add 3D Visualizer MCP to Claude Code?
Run claude mcp add 3d-visualizer -- uvx --from '3d-visualizer[mcp]' 3d-visualizer mcp --root /path/to/folder in your terminal. Add --scope user to make it available in every project.
How do I add 3D Visualizer MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does 3D Visualizer MCP provide?
It exposes 27 tools, including open_3d_files, open_depth_image, visualize_points, open_3d_url, update_3d_scene.
How do I install the MCP version for agents?
You can install it using uv tool install with the mcp and headless extras: uv tool install "3d-visualizer[mcp,headless]==0.5.0.dev0".
What tools are available in the default MCP configuration?
The default --tools core configuration exposes eight everyday tools.
Can I use this with PyTorch tensors?
Yes, the visualizer supports PyTorch inputs, including CPU or GPU tensors, whether they are detached or attached to autograd.