WebGPU Inspector MCP
WebGPU Inspector MCP is an MCP server that drives an instrumented Chrome/Chromium/Edge to capture, profile, inspect, and interactively debug WebGPU frames and WGSL shaders.
Browser automation: launch or attach to Chrome/Edge via CDP, open instrumented tabs, list pages, check status, and take composited page screenshots.
Frame capture: capture WebGPU frames (render/compute passes) with optional GPU timestamp profiling, payload caps, pass filters, and profilePasses mode.
Capture analysis: load
.wgpuc/.jsoncaptures and inspect summaries, command lists, GPU objects, WGSL shaders, validation errors, and heuristic performance/correctness issues.State inspection: resolve full draw/dispatch state (pipeline, bind groups, vertex/index buffers, draw params), decode vertex buffer attributes, and diff the state of two draws.
Performance profiling: diagnose frame budget and CPU/GPU/vsync bound verdicts, rank passes by GPU time, and identify bottlenecks like fillrate vs fragment-ALU with concrete suggestions.
Live GPU inspection: read current buffer contents and texture regions from a connected page (with stats and ASCII views) without a full capture, plus sample live frame rate, frame time, drops, and CPU submit cost.
Interactive shader debugging: start/step/continue WGSL debug sessions for compute, vertex, or fragment invocations; set breakpoints; inspect variables; get callstacks; and evaluate path expressions like
in.position.xor matrix/vector elements.
Launches and controls Chrome/Chromium via CDP, injecting WebGPU Inspector into pages to enable live frame capture, performance profiling, and resource inspection.
Provides tools for capturing and inspecting live WebGPU frames, profiling GPU timestamp performance, reading buffers and textures, and analyzing WGSL shaders to diagnose rendering issues.
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., "@WebGPU Inspector MCP Capture the next frame and profile its GPU timestamps."
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.
WebGPU Inspector MCP
An OpenCode / Model Context Protocol (MCP) server for WebGPU Inspector.
It allows AI assistants to drive Chrome/Chromium to capture live WebGPU frames, profile frame performance, inspect WGSL shaders, buffers, textures, diagnose WebGPU rendering issues, and step-debug WGSL compute, vertex, and fragment shaders interactively.
Features
Automated Browser Instrumentation: Launches Chromium/Chrome/Edge via CDP and injects WebGPU Inspector into every page before page scripts run.
Interactive Shader Debugging (8 Tools): Step-by-step WGSL debugging for compute, vertex, and fragment shaders with breakpoints, variable inspection, callstack unwinding, and expression evaluation.
Capture File Analysis & Live Inspection (21 Tools): Tools for browser control, frame capture, GPU timestamp profiling, live buffer/texture reads, draw state diffing, and shader inspection. Load and inspect
.wgpucbinary files or.jsonrecordings without running a browser.
Related MCP server: Chrome DevTools MCP
Installation
git clone git@github.com:lpenguin/webgpu_inspector_mcp.git
cd webgpu_inspector_mcp
npm installMCP Configuration
Add the server to your opencode.json (or Claude desktop configuration):
{
"mcp": {
"webgpu-inspector": {
"type": "local",
"command": ["node", "/path/to/webgpu_inspector_mcp/index.js"],
"enabled": true,
"environment": {
"WEBGPU_BRIDGE_PORT": "9690",
"WEBGPU_BRIDGE_CAPTURES_DIR": "/path/to/webgpu_inspector_mcp/captures"
}
}
}
}Shader Debugging Tools
The server provides 8 dedicated tools for interactive shader debugging powered by wgsl_reflect:
Tool | Description | Key Parameters |
| Starts an interactive debugging session for a compute dispatch, vertex draw, or fragment pixel. |
|
| Advances shader execution by stepping lines or instructions. |
|
| Continues execution until a line breakpoint is hit, the shader finishes, or |
|
| Sets, removes, or clears line breakpoints in the active session. |
|
| Returns the current callstack / call frames (innermost frame first) with function names and line numbers. |
|
| Inspects variables categorized by scope ( |
|
| Evaluates path expressions (e.g. |
|
| Stops and disposes an active debug session, freeing associated resources. |
|
Invocation Coordinates by Stage
When starting a debug session with shader_debug_start, provide the target invocation:
Compute:
{ "threadId": [x, y, z] }or{ "dispatchId": [x, y, z] }Vertex:
{ "vertexIndex": 0, "instanceIndex": 0 }(fetches vertex buffer attributes automatically)Fragment:
{ "pixelX": 100, "pixelY": 100 }(interpolates vertex outputs / varyings and@builtin(position)at pixel center)
Base Inspection & Profiling Tools (21 Tools)
Tool | Description |
| Launch a new instrumented Chrome/Edge instance via CDP. |
| Attach to an already-running Chrome/Edge on a remote debugging port. |
| Open a new instrumented tab in the controlled browser. |
| Check browser connection and instrumented pages status. |
| List connected WebGPU pages. |
| Capture a composited PNG screenshot of the presented canvas/page. |
| Request frame capture from connected page with optional GPU profiling. |
| List captures currently loaded in the store. |
| Load a |
| Get high-level summary of passes, draw calls, objects, and validation errors. |
| Profile GPU duration per pass and diagnose bottlenecks (fillrate vs ALU). |
| Return paginated list of GPU commands in capture. |
| Inspect GPU object descriptor (buffers, textures, pipelines). |
| Retrieve WGSL source code of a ShaderModule. |
| Get WebGPU validation errors recorded during capture. |
| Resolve pipeline, bound vertex buffers, index buffers, and bind groups for a draw/dispatch. |
| Decode captured vertex buffer payloads into typed attribute values. |
| Structurally diff the state between two draw calls. |
| Read live GPU buffer contents from connected page. |
| Read live GPU texture / render target region and return statistics and ASCII view. |
| Sample live frame rate, frame time variance, and CPU submit cost. |
Environment Variables
All environment variables are optional:
Variable | Default | Description |
|
| Directory where uploaded |
|
| Port for the local HTTP + WebSocket bridge that instrumented pages connect to. If the default port is already occupied by another session, the bridge automatically falls back to an OS-assigned free port. |
|
| Bind address for the local bridge server. |
| (auto-detected) | Custom binary path for Google Chrome, Chromium, or Microsoft Edge. Auto-detects standard system paths if omitted. |
| (none) | Optional auth token required for instrumented pages to connect to the bridge. |
| (bundled) | Path or URL to custom |
Available Tools
21 toolsanalyze_performanceA
Diagnose a capture's performance and return concrete improvement suggestions. Reports the frame budget and a CPU- / GPU- / vsync-bound verdict (needs a live capture for CPU/refresh context and profilePasses:true for GPU time), render passes ranked by GPU time (or fill workload when untimed) each annotated with render-target size/format/MSAA, blend usage, fragment-shader complexity, and a likely bottleneck (fillrate/ROP vs fragment-ALU), plus heuristic issues and ranked suggestions. Best paired with a capture taken via capture_frames({ profilePasses: true, payloads: "none" }).
Inputs: captureId.
attach_browserA
Attach to an already-running Chrome/Edge that was started with --remote-debugging-port. New tabs and navigations are instrumented automatically.
Inputs: browserURL, reloadPages.
browser_statusA
Report whether a controlled browser is connected, how it was connected, which targets are instrumented, and which pages have connected to the bridge.
Inputs: no named parameters.
capture_framesA
Ask a connected page to capture one or more WebGPU frames, then return a summary of the resulting capture (command/draw/pass counts, object counts, validation errors, flagged issues). Use list_pages first if unsure. For a PERFORMANCE analysis, set profilePasses:true (and payloads:"none" for a light perf-only capture) to measure per-pass GPU time, then call analyze_performance — treat a performance request as implying profilePasses:true.
Inputs: frames, pageId, passType, payloads, +4 more.
decode_vertex_bufferA
Decode the first N vertices of a captured vertex buffer into per-attribute numbers, so you can read e.g. 'attribute @location(2) (uv) = (0,0)' directly. Pass the bufferDataCommandIndex from get_draw_state (a setVertexBuffer command); the vertex layout is taken from the draw's pipeline automatically (or pass layout/pipelineId).
Inputs: commandIndex (required), firstN, layout, captureId, +2 more.
diff_drawsA
Structurally diff the resolved state (pipeline, bind groups, vertex/index bindings, draw params) of two draw commands — useful when a working draw and a broken draw share a pipeline and the difference must be in bound resources.
Inputs: cmdA (required), cmdB (required), captureId.
get_capture_summaryA
Summarize a capture: object counts by type, command counts by method, derived render statistics, shader entry points, validation error count, and heuristic performance/correctness issues. When the capture was taken with profilePasses:true it also includes gpuTiming (per-frame GPU time, slowest pass); when taken from a live page it includes frameBudget with a CPU/GPU/vsync bound verdict. For a focused performance report, use analyze_performance instead.
Inputs: captureId, includeIssues, includePasses, includeMethodCounts.
get_commandsA
Return a paginated, base64-stripped slice of a capture's command list. Each entry has its index, method, pass number, object, and arguments.
Inputs: limit, method, offset, captureId, +1 more.
get_draw_stateA
Resolve the full GPU state for a draw/dispatch command: the bound pipeline (and its vertex layout), bind groups per slot (with resource ids), vertex buffers per slot (each with the command index that captured its bytes), the index buffer, and draw params. Use this to diagnose what a specific draw actually read.
Inputs: commandIndex (required), captureId.
get_frame_statsA
Sample a live page's frame-health metrics over a short window (without taking a capture) and return aggregates: frame rate (fps), average and worst frame time, dropped frames, CPU submit time (main-thread cost per frame), the estimated display refresh interval, and a CPU-vs-GPU/vsync bound verdict. Use this to tell whether a page is dropping frames and whether it's CPU/main-thread bound; GPU time is not measured live, so a non-CPU verdict reads "GPU/vsync" — take a capture with profilePasses:true to measure GPU time and confirm. Requires the page's rendering loop to use requestAnimationFrame.
Inputs: pageId, durationMs.
get_objectA
Return one GPU object record from a capture (descriptor, label, stacktrace), with base64 payloads omitted.
Inputs: objectId (required), captureId.
get_shaderA
Return the WGSL source code of a ShaderModule object in a capture.
Inputs: objectId (required), captureId.
get_validation_errorsB
Return the WebGPU validation errors recorded during a capture.
Inputs: captureId.
launch_browserA
Launch a new Chrome/Edge instance controlled by this plugin. Every page it opens is automatically instrumented with the WebGPU Inspector — no extension and no page changes needed. Optionally navigate a first tab to a URL.
Inputs: url, headless, executablePath.
list_capturesA
List captures currently available to analyze (both live captures and capture files that were explicitly loaded).
Inputs: no named parameters.
list_pagesA
List browser pages currently connected to the live bridge. A page connects after it is instrumented (via launch_browser/open_page) or after it calls webgpuInspector.initializeServer() itself.
Inputs: no named parameters.
load_capture_fileA
Load a WebGPU Inspector capture file from disk (a .wgpuc binary saved by saveCaptureData() or the DevTools 'Save Capture' action, or a legacy .json capture) so it can be analyzed.
Inputs: path (required).
open_pageA
Open a new instrumented tab in the controlled browser and navigate it to a URL. Waits for the page to connect to the bridge and returns it ready to capture.
Inputs: url (required).
read_bufferA
Read the current contents of a live GPU buffer on a connected page, without taking a full capture. The inspector copies the buffer to a readback buffer, maps it, and returns the bytes decoded as the requested type. The source buffer must have been created with COPY_SRC usage (buffers created while a capture is armed are given COPY_SRC).
Inputs: bufferId (required), size, type, offset, +1 more.
read_textureA
Read a region of a live GPU texture / render target (G-buffer attachment, depth, canvas) on a connected page, without taking a full capture. Copies the texture to a readback buffer, decodes per its format, and returns per-channel min/max/mean, the fraction of unrasterised 'hole' texels (RGB all ~0 = the clear value showing through), and a small ASCII luminance view of the spatial pattern — never raw pixels. Pass a Texture id OR a TextureView id (a render pass attachment is a TextureView — it is resolved to its source texture automatically, so no get_object round-trip is needed). The texture must have COPY_SRC, which the inspector adds to every texture while a capture is armed. Note: reading an engine's POOLED render target after the frame can be unreliable (the pool may have recycled it); to see the final image use screenshot_page instead.
Inputs: textureId (required), x, y, layer, +4 more.
screenshot_pageA
Capture a PNG screenshot of an instrumented page and return it as an image. This reads the COMPOSITED page — the WebGPU canvas exactly as it was presented — so it is the reliable way to SEE what an engine rendered, independent of how it pools/aliases its render targets (reading a pooled target back after the frame is unreliable; the presented surface is not). Requires a page opened via launch_browser/open_page. Use this to visually verify a rendering change, not to inspect intermediate G-buffer contents (use read_texture / capture_frames for those).
Inputs: pageId, fullPage, selector.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct resource/action: capture lifecycle (list/load/summarize/analyze), object/shader/validation retrieval, low-level draw/buffer inspection, and live browser control with frame capture and texture reading. Even the two performance tools (get_capture_summary and analyze_performance) are explicitly differentiated, with the latter cross-referenced as the focused alternative. No two tools appear to do the same thing.
The vast majority follow a verb_noun pattern (list_captures, load_capture_file, analyze_performance, read_buffer, capture_frames, etc.). The only deviation is 'browser_status', which uses noun_verb and breaks the otherwise consistent style. This is a minor outlier that does not impede understanding.
21 tools is on the heavier side (borderline of the 16-25 'heavy' range), but the server covers two distinct domains: capture analysis and live browser instrumentation/debugging. Each tool fills a unique and necessary role within those domains, so the count is justified by the scope rather than being bloated or thin.
The surface covers the full workflow: capture acquisition (live or file), high-level summary and performance diagnosis, detailed object/state/vertex/buffer inspection, diffing draws, command listing, plus live browser control (launch/attach/open, page and target discovery, screenshot, frame capture, texture reads, and frame stats). There are no obvious gaps that would force an agent to work around missing functionality.
Maintenance
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Analytics, diagnostics and setup for browser extensions, driven by your AI agent
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to control and inspect a live Chrome browser through Chrome DevTools. Provides browser automation, performance analysis, debugging capabilities, and network request monitoring.2,158,323 npm58,617Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI coding assistants to control and inspect a live Chrome browser for automation, debugging, performance analysis, and screenshot capture through Chrome DevTools.262,158,323 npm3Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI coding assistants to control and inspect a live Chrome browser for automation, debugging, performance analysis, network monitoring, and DOM interaction through Chrome DevTools Protocol.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI coding assistants to control and inspect a live Chrome browser through Chrome DevTools for automation, debugging, and performance analysis.Apache 2.0