threejs-devtools-mcp
An MCP server that lets an AI inspect, live-preview and debug a running Three.js scene in the browser, then turn the changes into real code.
Inspect the scene —
scene_tree,object_details,find_objects,geometry_details,morph_targets,skeleton_details,layer_details,raycast,click_inspect,overlay_selectedMaterials & shaders — list/get details,
set_material_property,shader_list,shader_source,set_uniformTextures —
texture_list,texture_details,texture_preview(PNG),set_textureRenderer, camera, lights, fog, shadows, environment —
renderer_info/renderer_settings,camera_details,set_camera,set_light,fog_details/set_fog,shadow_details/set_shadow,scene_background,env_map_detailsAnimation & instancing —
animation_details,set_animation,instanced_mesh_details,set_instanced_meshPerformance & memory —
performance_snapshot,perf_monitor(FPS/jank),memory_stats,dispose_check,postprocessing_listVisual debugging —
highlight_object,toggle_wireframe,bounding_boxes,add_helper/remove_helper,toggle_overlay,console_capture,scene_diffLive preview edits — change materials, transforms, lights, camera, fog, shadows, layers; all runtime-only (lost on reload) and recorded so
pending_changesreturns before → after code for vanilla Three.js and R3F,revert_changesundoes themCapture & export —
take_screenshot,annotated_screenshot,scene_export(GLB),gltf_to_r3fEscape hatch & connection —
run_js(arbitrary JS with access toscene,renderer,camera),bridge_status,set_dev_port,set_dev_url(remote apps, inspection only)Beyond the schema — website audits, 60fps video frame capture, Playwright/Puppeteer helpers and ready-made skills
Integrates with Windsurf (by Codeium) for debugging and modifying Three.js scenes in real time.
Supports React Three Fiber projects, allowing AI to inspect and manipulate Three.js components.
Provides 59 tools for real-time inspection and modification of Three.js scenes, including objects, materials, shaders, textures, animations, performance monitoring, and memory diagnostics.
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., "@threejs-devtools-mcp show me the scene tree"
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.
threejs-devtools-mcp
MCP server for inspecting Three.js scenes in real time, trying changes live in the browser, and turning them into code. 69 tools cover objects, materials, shaders, textures, animation, performance and memory, plus website audits, video frame capture and Playwright helpers.
Zero changes to your project. Works with vanilla Three.js and React Three Fiber, on WebGLRenderer and WebGPURenderer.

Setup
1. Add the MCP server
claude mcp add threejs-devtools-mcp -- npx threejs-devtools-mcpAdd to claude_desktop_config.json:
{
"mcpServers": {
"threejs-devtools-mcp": {
"command": "npx",
"args": ["-y", "threejs-devtools-mcp"]
}
}
}Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"threejs-devtools-mcp": {
"command": "npx",
"args": ["-y", "threejs-devtools-mcp"]
}
}
}Or use the HTTP transport — see Cursor setup guide.
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"threejs-devtools-mcp": {
"command": "npx",
"args": ["-y", "threejs-devtools-mcp"]
}
}
}Add to .vscode/mcp.json:
{
"servers": {
"threejs-devtools-mcp": {
"command": "npx",
"args": ["-y", "threejs-devtools-mcp"]
}
}
}Add to opencode.json in your project:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"threejs-devtools-mcp": {
"type": "local",
"command": ["npx", "-y", "threejs-devtools-mcp"],
"enabled": true
}
}
}2. Start your dev server and open the browser
Start your Three.js dev server as usual (npm run dev). The MCP server auto-detects the port from package.json and opens a browser at localhost:9222 with the devtools bridge injected.
Keep the browser tab open. The MCP server talks to your scene through a WebSocket bridge. Close the tab = tools stop working.
3. Ask the AI about your scene
"show me the scene tree"
"why is my model invisible?"
"try the car in red" ← live preview, nothing saved
"keep it" ← written into your code
"audit this site for mobile"
"record a 5-second clip at 60 fps"Related MCP server: threejs-devtools-mcp
Look now vs. change the code
Every tool is labelled, so you and the AI always know what touches your files:
Tools | Your code | |
Inspect |
| untouched |
Live preview |
| untouched; lost on page reload |
Debug visual | wireframe, bounding boxes, helpers, overlay | untouched; never needed in code |
For code |
| the AI writes this into your source |
Every live-preview change is recorded. pending_changes returns each one as before → after with ready-to-paste code (vanilla Three.js and React Three Fiber) and where to find it in your project. revert_changes undoes them in the browser.
For websites and videos
web_audit: checks for a blurry canvas (pixel ratio, missing resize), battery drain (rendering while idle or off-screen), heavy textures (oversized, not KTX2), expensive shadows, wrong color space and too many draw calls. Each finding comes with the fix.capture_frames: records a frame sequence for promo clips and reels. Time is virtualised, so the output is perfectly smooth at 30/60 fps even if your scene renders slowly. You get theffmpegcommand for MP4/WebM.
Skills
Ready-made workflows show up as slash commands in Claude Code, Cursor and other clients: inspect-scene, try-look, apply-to-code, web-perf-audit, prepare-video, debug-invisible, playwright-setup.
Playwright & Puppeteer
Three ways to connect, same tools in all of them: your own browser (default), a Chrome launched by the server (HEADLESS / CDP_PORT, shareable with Playwright MCP), or your own tests:
import { attachDevtools, waitForScene, threeCall } from 'threejs-devtools-mcp/playwright';
await attachDevtools(context, { connect: false });
await page.goto('http://localhost:5173');
await waitForScene(page);
expect((await threeCall(page, 'object_details', { name: 'Car' })).visible).toBe(true);See Browsers, Puppeteer & Playwright.
In-browser overlay
A built-in devtools panel with live performance stats, interactive scene graph, material editor, and 3D object preview. Activated automatically or via the toggle_overlay tool.

Tip: name your objects
Unnamed objects show as (unnamed) in the scene tree. Named objects are easier to find and modify:
// Three.js
mesh.name = "player";// React Three Fiber
<mesh name="player" geometry={geometry} material={material} />Documentation
Tools reference — all 69 tools by mode, skills, parameters
Browsers, Puppeteer & Playwright — connection modes, e2e tests, CI tips
Advanced setup — animations, scene export, configuration, transports
Cursor setup — step-by-step guide for Cursor
Token-efficient workflow — best practices for saving context
License
MIT
Available Tools
69 toolsadd_helperA
[DEBUG VISUAL] Temporary visual aid in the browser. Nothing to put in code. Add a debug helper to an object: box, axes, skeleton, arrow, grid, camera frustum, light helpers, plane.
Inputs: size, type, color, length, +5 more.
animation_detailsARead-onlyIdempotent
[INSPECT] Read-only. AnimationMixers with their actions, clips, weights and playback state.
Inputs: no named parameters.
annotated_screenshotARead-onlyIdempotent
[INSPECT] Read-only. Screenshot with object names drawn at their screen positions ([M]esh, [L]ight, [G]roup, [C]amera). Best for understanding layout.
Inputs: width, height.
batched_mesh_detailsARead-onlyIdempotent
[INSPECT] Read-only. BatchedMesh: geometry counts, draw ranges, instance visibility. Lists all if no name/uuid.
Inputs: name, uuid.
bounding_boxesA
[DEBUG VISUAL] Temporary visual aid in the browser. Nothing to put in code. Show/hide bounding boxes — debug frustum culling and object bounds.
Inputs: name, uuid, clear, color, +4 more.
bridge_statusCIdempotent
[CONNECTION] Configures the devtools server. Bridge connection, proxy target, and how to attach Playwright to the same browser.
Inputs: no named parameters.
camera_detailsARead-onlyIdempotent
[INSPECT] Read-only. Active camera: type, position, FOV, near/far, aspect.
Inputs: no named parameters.
capture_framesARead-only
[INSPECT] Read-only. Record a frame sequence for a video. Time is virtualised, so frames are exactly 1/fps apart and smooth even if rendering is slow. Saves numbered images to screenshots/sequence-/ and returns an ffmpeg command.
Inputs: fps, width, format, height, +1 more.
click_inspectARead-onlyIdempotent
[INSPECT] Read-only. Click-to-inspect: the cursor becomes a crosshair — tell the user to click an object in the 3D view. Returns that object.
Inputs: timeout.
clipping_detailsARead-onlyIdempotent
[INSPECT] Read-only. Clipping planes: renderer global, per-material, ClippingGroup objects.
Inputs: no named parameters.
console_captureBRead-onlyIdempotent
[INSPECT] Read-only. Recent browser console output (log/warn/error).
Inputs: clear, level, limit.
dispose_checkARead-onlyIdempotent
[INSPECT] Read-only. Leak detection: geometries/textures tracked by the renderer but no longer in the scene.
Inputs: no named parameters.
draw_call_breakdownARead-onlyIdempotent
[INSPECT] Read-only. Per-object draw call and triangle cost, sorted by cost. Flags multi-material objects and hidden geometry.
Inputs: no named parameters.
env_map_detailsBRead-onlyIdempotent
[INSPECT] Read-only. Environment maps: scene.environment, scene.background, per-material envMap.
Inputs: no named parameters.
find_objectsBRead-onlyIdempotent
[INSPECT] Read-only. Search objects by type, material, visibility, name pattern, or custom property.
Inputs: type, limit, value, visible, +5 more.
fog_detailsARead-onlyIdempotent
[INSPECT] Read-only. Scene fog: type (Fog/FogExp2), color, near/far or density.
Inputs: no named parameters.
geometry_detailsBRead-onlyIdempotent
[INSPECT] Read-only. Geometry of a mesh: vertices, attributes, index, bounding box, morph attributes.
Inputs: name, uuid.
gltf_to_r3fARead-onlyIdempotent
[FOR CODE] Output is meant to be written into the project source files. Convert a GLB/glTF file into a React Three Fiber component (like gltfjsx).
Inputs: filePath (required), preload, typescript.
highlight_objectA
[DEBUG VISUAL] Temporary visual aid in the browser. Nothing to put in code. Highlight an object with wireframe, or toggle its visibility, to point it out.
Inputs: mode, name, uuid, enabled.
instanced_mesh_detailsARead-onlyIdempotent
[INSPECT] Read-only. InstancedMesh: count, capacity, sample transforms, instance colors and custom attributes.
Inputs: name, uuid, startIndex, sampleCount.
layer_detailsBRead-onlyIdempotent
[INSPECT] Read-only. Camera layer mask and objects with non-default layers.
Inputs: no named parameters.
material_detailsBRead-onlyIdempotent
[INSPECT] Read-only. Full material properties: colors, PBR/physical params, maps, uniforms, defines, NodeMaterial (TSL) slots.
Inputs: name, uuid.
material_listARead-onlyIdempotent
[INSPECT] Read-only. All materials in the scene with type, color, transparency.
Inputs: no named parameters.
memory_statsBRead-onlyIdempotent
[INSPECT] Read-only. GPU memory: geometry buffers, texture VRAM, instance data, top textures by size.
Inputs: no named parameters.
morph_targetsARead-onlyIdempotent
[INSPECT] Read-only. Meshes with morph targets: target names and current influences.
Inputs: no named parameters.
object_detailsBRead-onlyIdempotent
[INSPECT] Read-only. Detailed info about one object by name, uuid, or dot path.
Inputs: name, path, uuid.
overlay_selectedARead-onlyIdempotent
[INSPECT] Read-only. Everything about the object the user selected in the overlay: materials, geometry, transforms, textures, uniforms, shadows.
Inputs: no named parameters.
pending_changesARead-onlyIdempotent
[FOR CODE] Output is meant to be written into the project source files. Everything changed with live-preview tools since the last clear: before → after per property, plus ready-to-paste code (vanilla Three.js and/or React Three Fiber) and where to find each target. Use it to persist a preview into source; call again with clear=true once the code is updated.
Inputs: clear, style.
perf_monitorBRead-onlyIdempotent
[INSPECT] Read-only. Record FPS and frame times for N seconds: avg/min/max, percentiles, spikes, jank.
Inputs: duration, includeFrameTimes.
performance_snapshotBRead-onlyIdempotent
[INSPECT] Read-only. Draw calls, triangles, instanced meshes, object counts by type.
Inputs: no named parameters.
postprocessing_listARead-onlyIdempotent
[INSPECT] Read-only. EffectComposer passes: render passes, shader passes, effects (bloom, SSAO, …).
Inputs: no named parameters.
raycastBRead-onlyIdempotent
[INSPECT] Read-only. Cast a ray from the camera through screen coordinates and return hit objects.
Inputs: x (required), y (required), maxHits.
remove_helperA
[DEBUG VISUAL] Temporary visual aid in the browser. Nothing to put in code. Remove a helper added with add_helper.
Inputs: helperId (required).
renderer_infoARead-onlyIdempotent
[INSPECT] Read-only. Renderer stats and backend (WebGL / WebGPU): draw calls, triangles, memory, capabilities.
Inputs: no named parameters.
renderer_settingsARead-onlyIdempotent
[INSPECT] Read-only. Renderer configuration: toneMapping, exposure, colorSpace, shadowMap, pixelRatio.
Inputs: no named parameters.
revert_changesAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Undo live-preview changes in the browser (all, or selected ids from pending_changes), newest first.
Inputs: ids.
run_jsADestructive
[DEBUG VISUAL] Temporary visual aid in the browser. Nothing to put in code.
Run JavaScript in the page with scene, renderer, camera, gl in scope; return a value to get it back. Changes made here are NOT recorded in pending_changes — prefer the set_* tools for anything the user may want to keep.
Inputs: code (required).
scene_backgroundARead-onlyIdempotent
[INSPECT] Read-only. Scene background, environment map (IBL), backgroundBlurriness/Intensity, color management.
Inputs: no named parameters.
scene_diffARead-onlyIdempotent
[INSPECT] Read-only. Compare scene state over time: first call saves a snapshot, next call lists added/removed/modified objects.
Inputs: action.
scene_exportARead-only
[INSPECT] Read-only. Export the scene or one object as GLB/glTF into screenshots/. Needs GLTFExporter in the app (the error explains setup).
Inputs: name, uuid, binary.
scene_treeARead-onlyIdempotent
[INSPECT] Read-only. Scene hierarchy. Compact text tree by default (~2KB); compact=false for full JSON with positions/geometry.
Inputs: depth, types, compact, maxChildren.
set_animationAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Control playback: mixer timeScale/time, action play/stop/pause/weight by clip name.
Inputs: play, stop, time, clipName, +5 more.
set_cameraAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Change the active camera: position, rotation, FOV, near/far, zoom, ortho bounds.
Inputs: far, fov, top, left, +7 more.
set_clippingAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Change clipping planes on the renderer (global) or a material.
Inputs: name, uuid, planes, target, +4 more.
set_dev_portBIdempotent
[CONNECTION] Configures the devtools server. Point the proxy at another local dev server port.
Inputs: port (required).
set_dev_urlBIdempotent
[CONNECTION] Configures the devtools server. Inspect a remote Three.js app by URL. Source code changes are not possible in remote mode.
Inputs: url (required).
set_fogAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Change scene fog (color, near/far or density) and the background color.
Inputs: far, near, color, density, +1 more.
set_instanced_meshAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Change InstancedMesh count, visibility, frustumCulled.
Inputs: name, uuid, count, visible, +1 more.
set_layersAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Set layers on an object or the camera.
Inputs: mask, name, uuid, layer, +2 more.
set_lightAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Change a light: color, intensity, position, castShadow, groundColor (HemisphereLight).
Inputs: name, uuid, color, position, +3 more.
set_material_propertyAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Set a material property. Accepts the material name or the name of a mesh that uses it.
Inputs: value (required), property (required), name, uuid.
set_morph_targetAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Set a morph target influence.
Inputs: influence (required), name, uuid, index, +1 more.
set_object_transformAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Set position, rotation, scale, or visibility of an object.
Inputs: name, uuid, scale, visible, +2 more.
set_postprocessingAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Enable/disable passes, set pass uniforms or effect parameters. Without a pass, lists passes.
Inputs: enabled, passName, uniforms, passIndex, +2 more.
set_rendererAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Change renderer settings: tone mapping, exposure, color space, pixel ratio, shadows.
Inputs: pixelRatio, sortObjects, toneMapping, shadowMapType, +4 more.
set_shadowAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Change shadow casting/receiving on any object, and bias/mapSize/shadow camera on lights.
Inputs: bias, name, uuid, radius, +11 more.
set_textureAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Change texture sampling and transform: wrap, filter, anisotropy, repeat, offset, rotation, colorSpace.
Inputs: name, uuid, flipY, wrapS, +8 more.
set_uniformAIdempotent
[LIVE PREVIEW] Changes the scene in the browser only — NOT saved to source code, lost on reload. Recorded in pending_changes (→ code edits) and undoable with revert_changes. Set a ShaderMaterial uniform.
Inputs: value (required), uniform (required), name, uuid.
shader_listBRead-onlyIdempotent
[INSPECT] Read-only. Compiled shader programs with their materials (WebGL).
Inputs: no named parameters.
shader_sourceARead-onlyIdempotent
[INSPECT] Read-only. Vertex/fragment GLSL source and uniforms of a material. NodeMaterial (TSL) has no GLSL — use material_details.
Inputs: materialName, materialUuid.
shadow_detailsARead-onlyIdempotent
[INSPECT] Read-only. Shadow maps: global settings, per-light bias/mapSize/camera frustum, casters and receivers.
Inputs: no named parameters.
skeleton_detailsBRead-onlyIdempotent
[INSPECT] Read-only. Skeletons and bones of SkinnedMesh objects.
Inputs: no named parameters.
take_screenshotARead-onlyIdempotent
[INSPECT] Read-only. Screenshot of the current scene (also saved as PNG in screenshots/).
Inputs: width, height.
texture_detailsCRead-onlyIdempotent
[INSPECT] Read-only. Detailed info about one texture.
Inputs: name, uuid.
texture_listARead-onlyIdempotent
[INSPECT] Read-only. All textures: size, format, wrap, filter settings.
Inputs: no named parameters.
texture_previewARead-onlyIdempotent
[INSPECT] Read-only. Show a texture as a PNG image. Use texture_list to find names/UUIDs.
Inputs: name, uuid, maxSize.
toggle_overlayA
[DEBUG VISUAL] Temporary visual aid in the browser. Nothing to put in code. In-browser inspector panel: live FPS, draw calls, scene tree, materials, lights. Clicking a tree item highlights it.
Inputs: enabled.
toggle_wireframeA
[DEBUG VISUAL] Temporary visual aid in the browser. Nothing to put in code. Wireframe on all materials or one object.
Inputs: name, uuid, enabled.
web_auditBRead-onlyIdempotent
[INSPECT] Read-only. Website health check: pixel ratio, canvas resize, idle/off-screen rendering, antialias cost, oversized or uncompressed textures, shadow cost, color space, draw calls. Each finding has a concrete fix.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 69 tools
The server has clear category tags and distinct targets for most tools, but overlapping clusters exist in performance/memory inspection (renderer_info, performance_snapshot, web_audit, draw_call_breakdown, memory_stats, dispose_check) and debug visuals (highlight_object, toggle_wireframe, bounding_boxes, add_helper), where an agent could misselect despite descriptions.
All tool names are lower_snake_case and follow predictable patterns (noun_details/list for inspection, set_* for live preview, toggle_*/add_*/remove_* for debug), but not a strict verb_noun convention and includes abbreviations (perf, env, gltf) and verb-only names like raycast.
69 tools is an extreme mismatch for a single MCP server, far beyond the 3-15 well-scoped range; many tools are highly specialized and could be consolidated.
The surface covers inspection, live preview, code persistence, and connection setup across nearly all Three.js subsystems, with only minor gaps like direct scene background/environment setters and object creation/deletion (workable via run_js).
Maintenance
Related MCP Connectors
Create, inspect, validate, and save editable 3D building scenes with Pascal's MCP server.
Generate, edit, and deploy immersive 3D/WebGL web projects from any MCP assistant.
Official MCP server for Softhills 3D/2D Visualization SDKs, API documentation, and code examples.
Build and inspect browser-based 3D games: projects, scenes, Lua scripts, assets and publishing.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for inspecting and manipulating Three.js/Threlte scenes in real-time.8MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect and modify live Three.js scenes in real time through 59 tools covering objects, materials, shaders, textures, animations, performance monitoring, memory diagnostics, and code generation. Works with vanilla Three.js, React Three Fiber, and any framework without changing your project, using an injected browser bridge and in-page devtools overlay.5,671 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect Three.js and React Three Fiber scenes in a live browser and experiment with changes to objects, materials, shaders, textures, lighting, animation and performance without touching project code. Previewed adjustments can be converted into ready-to-paste vanilla Three.js or R3F source code, and the server also offers website performance audits, frame capture for video, and Playwright/Puppeteer helpers.5,671 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to inspect and edit live Three.js scenes in the browser — objects, materials, shaders, textures, lights, animation, performance and memory — with 69 tools covering scene trees, screenshots, website audits and video frame capture. Changes can be previewed live with zero project modifications, then converted into ready-to-paste vanilla Three.js or React Three Fiber code.5,671 npmMIT