Skip to main content
Glama
WebGPU Inspector MCP
by lpenguin

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 .wgpuc binary files or .json recordings 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 install

MCP 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

shader_debug_start

Starts an interactive debugging session for a compute dispatch, vertex draw, or fragment pixel.

captureId, commandIndex, stage ("compute", "vertex", "fragment"), entryPoint, code, shaderCaptureId, shaderObjectId, invocation, breakpoints, constants, sessionId

shader_debug_step

Advances shader execution by stepping lines or instructions.

sessionId, action ("step_next", "step_into", "step_over", "step_out"), count

shader_debug_continue

Continues execution until a line breakpoint is hit, the shader finishes, or maxSteps is reached.

sessionId, maxSteps (default: 50000)

shader_debug_set_breakpoints

Sets, removes, or clears line breakpoints in the active session.

sessionId, add (array of line numbers), remove (array of line numbers), clearAll (boolean)

shader_debug_get_stack

Returns the current callstack / call frames (innermost frame first) with function names and line numbers.

sessionId

shader_debug_get_variables

Inspects variables categorized by scope (locals, inputs, globals, constants, resources).

sessionId, scope ("all", "locals", "inputs", "globals", "constants", "resources"), filter, maxDepth

shader_debug_eval

Evaluates path expressions (e.g. in.position.x, uFrame.cameraPos.xyz, params.multiplier, matrix[1][2]).

sessionId, expression (or path)

shader_debug_stop

Stops and disposes an active debug session, freeing associated resources.

sessionId

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_browser

Launch a new instrumented Chrome/Edge instance via CDP.

attach_browser

Attach to an already-running Chrome/Edge on a remote debugging port.

open_page

Open a new instrumented tab in the controlled browser.

browser_status

Check browser connection and instrumented pages status.

list_pages

List connected WebGPU pages.

screenshot_page

Capture a composited PNG screenshot of the presented canvas/page.

capture_frames

Request frame capture from connected page with optional GPU profiling.

list_captures

List captures currently loaded in the store.

load_capture_file

Load a .wgpuc or .json capture file from disk.

get_capture_summary

Get high-level summary of passes, draw calls, objects, and validation errors.

analyze_performance

Profile GPU duration per pass and diagnose bottlenecks (fillrate vs ALU).

get_commands

Return paginated list of GPU commands in capture.

get_object

Inspect GPU object descriptor (buffers, textures, pipelines).

get_shader

Retrieve WGSL source code of a ShaderModule.

get_validation_errors

Get WebGPU validation errors recorded during capture.

get_draw_state

Resolve pipeline, bound vertex buffers, index buffers, and bind groups for a draw/dispatch.

decode_vertex_buffer

Decode captured vertex buffer payloads into typed attribute values.

diff_draws

Structurally diff the state between two draw calls.

read_buffer

Read live GPU buffer contents from connected page.

read_texture

Read live GPU texture / render target region and return statistics and ASCII view.

get_frame_stats

Sample live frame rate, frame time variance, and CPU submit cost.

Environment Variables

All environment variables are optional:

Variable

Default

Description

WEBGPU_BRIDGE_CAPTURES_DIR

<cwd>/captures

Directory where uploaded .wgpuc frame captures are stored. If not set, it defaults to creating a captures/ folder in the current working directory. Setting an explicit absolute path keeps all captures in one dedicated location.

WEBGPU_BRIDGE_PORT

9690

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.

WEBGPU_BRIDGE_HOST

127.0.0.1

Bind address for the local bridge server.

WEBGPU_BRIDGE_CHROME

(auto-detected)

Custom binary path for Google Chrome, Chromium, or Microsoft Edge. Auto-detects standard system paths if omitted.

WEBGPU_BRIDGE_TOKEN

(none)

Optional auth token required for instrumented pages to connect to the bridge.

WEBGPU_INSPECTOR_SCRIPT

(bundled)

Path or URL to custom webgpu_inspector.js injection script. Defaults to the bundled file.

Available Tools

21 tools
analyze_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

    A4/5.0

    Scored across 21 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers