Skip to content
Back to search

renderdoc-mcp

MCP server for RenderDoc — AI-assisted GPU frame capture analysis

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/linkingooo--renderdoc-mcp/badge.svg)](/listings/linkingooo--renderdoc-mcp)

HTML

<a href="/listings/linkingooo--renderdoc-mcp"><img src="/api/listings/linkingooo--renderdoc-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Prerequisites

- **Python 3.10+** - **RenderDoc** installed ([download](https://renderdoc.org/builds)) - You need the `renderdoc.pyd` (Windows) or `renderdoc.so` (Linux) Python module - It ships with every RenderDoc installation

2. Install

git clone https://github.com/Linkingooo/renderdoc-mcp.git
cd renderdoc-mcp
pip install -e .

3. Find your `renderdoc.pyd` path

The Python module is in your RenderDoc install directory:

| Platform | Typical path | |----------|-------------| | Windows | `C:\Program Files\RenderDoc\renderdoc.pyd` | | Linux | `/usr/lib/renderdoc/librenderdoc.so` or where you built it |

You need the **directory** containing this file.

4. Configure your MCP client

<details> <summary><b>Claude Desktop</b></summary>

Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "renderdoc": {
      "command": "python",
      "args": ["-m", "renderdoc_mcp"],
      "env": {
        "RENDERDOC_MODULE_PATH": "C:\\Program Files\\RenderDoc"
      }
    }
  }
}

</details>

<details> <summary><b>Claude Code</b></summary>

Add to `.claude/settings.json`:

{
  "mcpServers": {
    "renderdoc": {
      "command": "python",
      "args": ["-m", "renderdoc_mcp"],
      "env": {
        "RENDERDOC_MODULE_PATH": "C:\\Program Files\\RenderDoc"
      }
    }
  }
}

</details>

<details> <summary><b>Run standalone</b></summary>

# Set the module path
export RENDERDOC_MODULE_PATH="/path/to/renderdoc"   # Linux/macOS
set RENDERDOC_MODULE_PATH=C:\Program Files\RenderDoc  # Windows

# Run
python -m renderdoc_mcp

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 310 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # renderdoc-mcp
  2. <div align="center">
  3. <h2>⚠️ Disclaimer</h2>
  4. $\Large\color{#ff69b4}{\textsf{This is a personal }}$ $\Large\color{#ff69b4}{\mathtt{✨ vibe\text{-}coding ✨}}$ $\Large\color{#ff69b4}{\textsf{project —}}$
  5. $\Large\color{#ff69b4}{\textsf{built for fun, not for production use.}}$
  6. $\small\color{gray}{\textsf{I have no idea why this repo has so many stars...}}$
  7. <img src="assets/crying.gif" width="64" />
  8. </div>
  9. MCP server for [RenderDoc](https://renderdoc.org/) — let AI assistants analyze GPU frame captures (`.rdc` files) for graphics debugging and performance analysis.
  10. Built on the [Model Context Protocol](https://modelcontextprotocol.io/), works with Claude Desktop, Claude Code, and any MCP-compatible client.
  11. ## Features
  12. - **42 tools** covering the full RenderDoc analysis workflow
  13. - **10 high-level tools** for one-call analysis (draw call state, frame overview, diff, batch export, pixel region sampling, etc.)
  14. - **3 built-in prompts** for guided debugging
  15. - **Human-readable output** — blend modes, depth functions, topology shown as names not numbers
  16. - **GPU quirk detection** — auto-identifies Adreno/Mali/PowerVR/Apple-specific pitfalls from driver name
  17. - **Headless** — no GUI needed, runs entirely via RenderDoc's Python replay API
  18. - **Pure Python** — single `pip install`, no build step
  19. - Supports D3D11, D3D12, OpenGL, Vulkan, OpenGL ES captures
  20. ## Quick Start
  21. ### 1. Prerequisites
  22. - **Python 3.10+**
  23. - **RenderDoc** installed ([download](https://renderdoc.org/builds))
  24. - You need the `renderdoc.pyd` (Windows) or `renderdoc.so` (Linux) Python module
  25. - It ships with every RenderDoc installation
  26. ### 2. Install
  27. ```bash
  28. git clone https://github.com/Linkingooo/renderdoc-mcp.git
  29. cd renderdoc-mcp
  30. pip install -e .
  31. ```
  32. ### 3. Find your `renderdoc.pyd` path
  33. The Python module is in your RenderDoc install directory:
  34. | Platform | Typical path |
  35. |----------|-------------|
  36. | Windows | `C:\Program Files\RenderDoc\renderdoc.pyd` |
  37. | Linux | `/usr/lib/renderdoc/librenderdoc.so` or where you built it |
  38. You need the **directory** containing this file.
  39. ### 4. Configure your MCP client
  40. <details>
  41. <summary><b>Claude Desktop</b></summary>
  42. Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
  43. ```json
  44. {
  45. "mcpServers": {
  46. "renderdoc": {
  47. "command": "python",
  48. "args": ["-m", "renderdoc_mcp"],
  49. "env": {
  50. "RENDERDOC_MODULE_PATH": "C:\\Program Files\\RenderDoc"
  51. }
  52. }
  53. }
  54. }
  55. ```
  56. </details>
  57. <details>
  58. <summary><b>Claude Code</b></summary>
  59. Add to `.claude/settings.json`:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "renderdoc": {
  64. "command": "python",
  65. "args": ["-m", "renderdoc_mcp"],
  66. "env": {
  67. "RENDERDOC_MODULE_PATH": "C:\\Program Files\\RenderDoc"
  68. }
  69. }
  70. }
  71. }
  72. ```
  73. </details>
  74. <details>
  75. <summary><b>Run standalone</b></summary>
  76. ```bash
  77. # Set the module path
  78. export RENDERDOC_MODULE_PATH="/path/to/renderdoc" # Linux/macOS
  79. set RENDERDOC_MODULE_PATH=C:\Program Files\RenderDoc # Windows
  80. # Run
  81. python -m renderdoc_mcp
  82. ```
  83. </details>
  84. ## Usage Examples
  85. Once configured, just talk to your AI assistant:
  86. > "Open `frame.rdc` and show me what's happening in the frame"
  87. > "Find the draw call that renders the character model and check its pipeline state"
  88. > "Why is my shadow map rendering black? Check the depth pass"
  89. > "Analyze performance — are there any redundant draw calls?"
  90. ### Typical Tool Flow
  91. ```
  92. open_capture("frame.rdc") # Load the capture
  93. ├── get_capture_info() # API, GPU, known_gpu_quirks
  94. ├── get_frame_overview() # Frame-level stats and render passes
  95. ├── get_draw_call_state(142) # Complete draw call state in one call
  96. ├── diff_draw_calls(140, 142) # Compare two draw calls (with implications)
  97. ├── export_draw_textures(142, "./tex/") # Batch export all bound textures
  98. ├── save_render_target(142, "./rt.png") # Save render target snapshot
  99. ├── analyze_render_passes() # Auto-detect render pass boundaries
  100. ├── find_draws(blend=True, min_vertices=1000) # Search by rendering state
  101. ├── sample_pixel_region(rt_id, 0,0,512,512) # Scan RT region for NaN/Inf/negatives
  102. ├── pixel_history(id, 512, 384) # Debug a specific pixel
  103. ├── export_mesh(142, "./mesh.obj") # Export mesh as OBJ
  104. └── close_capture() # Clean up
  105. ```
  106. For performance and diagnostic analysis:
  107. ```
  108. get_pass_timing(granularity="pass") # Find most expensive render passes
  109. analyze_overdraw() # Fill-rate pressure estimate
  110. analyze_bandwidth() # Memory bandwidth estimate
  111. analyze_state_changes() # Batching opportunities
  112. diagnose_negative_values() # Find NaN/Inf/negative color values (爆闪)
  113. diagnose_precision_issues() # R11G11B10, D16, SRGB mismatches
  114. diagnose_reflection_mismatch() # Reflection artifact diagnosis
  115. diagnose_mobile_risks() # Comprehensive mobile GPU risk check
  116. ```
  117. For lower-level inspection, all granular tools remain available:
  118. ```
  119. set_event(142) # Navigate to a draw call
  120. ├── get_pipeline_state() # Inspect rasterizer/blend/depth
  121. ├── get_shader_bindings("pixel") # Check what textures/buffers are bound
  122. ├── get_cbuffer_contents("pixel", 0, filter="ibl") # Read shader constants (filterable)
  123. ├── disassemble_shader("pixel", search="SampleSH") # Shader code with context search
  124. └── save_texture(id, "rt.png") # Export a specific texture
  125. ```
  126. ## Tools
  127. ### Session Management (4)
  128. | Tool | Description |
  129. |------|-------------|
  130. | `open_capture` | Open a `.rdc` file (auto-closes previous) |
  131. | `close_capture` | Close current capture and free resources |
  132. | `get_capture_info` | Capture metadata: API, action count, resolution, **known_gpu_quirks** (Adreno/Mali/PowerVR/Apple) |
  133. | `get_frame_overview` | **Frame-level statistics**: action counts by type, texture/buffer memory, render targets, resolution |
  134. ### Event Navigation (5)
  135. | Tool | Description |
  136. |------|-------------|
  137. | `list_actions` | List the draw call / action tree — supports `filter` (name substring) and `event_type` (draw/clear/copy…) |
  138. | `get_action` | Full detail for a single action |
  139. | `set_event` | Navigate to an event (**required** before pipeline queries) |
  140. | `search_actions` | Search by name pattern and/or action flags |
  141. | `find_draws` | **Search draw calls by rendering state**: blend, min vertices, texture/shader/RT binding |
  142. ### Pipeline Inspection (4)
  143. | Tool | Description |
  144. |------|-------------|
  145. | `get_pipeline_state` | Full state: topology, viewports, rasterizer, blend, depth, stencil (human-readable enums) |
  146. | `get_shader_bindings` | Constant buffers, SRVs, UAVs, samplers for a shader stage |
  147. | `get_vertex_inputs` | Vertex attributes, vertex/index buffer bindings |
  148. | `get_draw_call_state` | **One-call draw analysis**: action info, blend formula, depth, stencil, rasterizer, textures with sizes, RTs, shaders |
  149. ### Resource Analysis (4)
  150. | Tool | Description |
  151. |------|-------------|
  152. | `list_textures` | All textures (filterable by format, min width) |
  153. | `list_buffers` | All buffers (filterable by min size) |
  154. | `list_resources` | All named resources (filterable by type, name pattern) |
  155. | `get_resource_usage` | Which events read/write a resource |
  156. ### Data Extraction (8)
  157. | Tool | Description |
  158. |------|-------------|
  159. | `save_texture` | Export to PNG, JPG, BMP, TGA, HDR, EXR, or DDS |
  160. | `get_buffer_data` | Read buffer bytes (hex dump or float32 array) |
  161. | `pick_pixel` | RGBA value at a coordinate |
  162. | `get_texture_stats` | Per-channel min/max/avg with **anomaly detection** (NaN/Inf/negative); supports `all_slices` for cubemaps |
  163. | `read_texture_pixels` | Read a rectangular region of pixels (up to 64×64) with per-pixel anomaly flags |
  164. | `export_draw_textures` | **Batch export** all textures bound to a draw call (auto-names, skips placeholders) |
  165. | `save_render_target` | **Save RT snapshot** at an event (color + optional depth) |
  166. | `export_mesh` | **Export mesh as OBJ** with positions, normals, UVs from post-VS data |
  167. ### Shader Analysis (3)
  168. | Tool | Description |
  169. |------|-------------|
  170. | `disassemble_shader` | Shader disassembly with **auto fallback chain**; supports `search` (keyword + context) and `line_range` |
  171. | `get_shader_reflection` | Input/output signatures, resource binding layout |
  172. | `get_cbuffer_contents` | Actual constant buffer variable values; supports `filter` for variable name substring |
  173. ### Advanced (6)
  174. | Tool | Description |
  175. |------|-------------|
  176. | `pixel_history` | Full per-pixel modification history across all events |
  177. | `get_post_vs_data` | Post-transform vertex data (VS out / GS out) |
  178. | `diff_draw_calls` | **Compare two draw calls** — shows state differences with human-readable implications |
  179. | `analyze_render_passes` | **Auto-detect render pass boundaries** by Clear/RT switches, summarize each pass |
  180. | `sample_pixel_region` | **Uniform-grid scan** of an RT region — detects NaN/Inf/negative/overexposed hotspots |
  181. | `debug_shader_at_pixel` | **Per-pixel shader debug** — returns variable trace or pixel value + shader info as fallback |
  182. ### Performance Analysis (4)
  183. | Tool | Description |
  184. |------|-------------|
  185. | `get_pass_timing` | Most expensive render passes — uses GPU counters if available, falls back to triangle-count heuristic |
  186. | `analyze_overdraw` | Overdraw estimate per render target group |
  187. | `analyze_bandwidth` | Write/read bandwidth estimate per render target |
  188. | `analyze_state_changes` | Finds redundant state-change patterns and batching opportunities |
  189. ### Diagnostics (4)
  190. | Tool | Description |
  191. |------|-------------|
  192. | `diagnose_negative_values` | Scans all float RTs for negative/NaN/Inf — finds first event introducing them, detects TAA accumulation |
  193. | `diagnose_precision_issues` | Checks R11G11B10 sign-bit loss, shallow depth buffers, SRGB/linear mismatches |
  194. | `diagnose_reflection_mismatch` | Compares reflection passes against main scene draws — finds shader/blend/format causes |
  195. | `diagnose_mobile_risks` | Comprehensive check across precision / performance / compatibility / GPU-specific risk categories |
  196. ## Prompts
  197. Built-in prompt templates to guide AI through common workflows:
  198. | Prompt | Description |
  199. |--------|-------------|
  200. | `debug_draw_call` | Deep-dive a single draw call: pipeline → shaders → cbuffers → outputs |
  201. | `find_rendering_issue` | Systematic diagnosis from a problem description |
  202. | `analyze_performance` | Frame-wide perf analysis: pass timing, overdraw, bandwidth, state changes |
  203. ## How It Works
  204. ```
  205. AI Assistant ←—MCP—→ renderdoc-mcp server ←—Python API—→ renderdoc.pyd ←→ GPU replay
  206. ```
  207. The server uses RenderDoc's headless replay API (`renderdoc.pyd`) to:
  208. 1. Open `.rdc` capture files without the GUI
  209. 2. Replay frames and query pipeline state at any event
  210. 3. Extract textures, buffers, shader data, and pixel history
  211. 4. Return structured JSON for the AI to reason about
  212. ## Development
  213. ```bash
  214. # Install in dev mode
  215. pip install -e .
  216. # Run tests (no RenderDoc needed — uses mocks)
  217. python -m pytest tests/ -v
  218. # Project structure
  219. src/renderdoc_mcp/
  220. ├── server.py # FastMCP server, 3 prompt definitions
  221. ├── session.py # Capture lifecycle, resource/texture caches (singleton)
  222. ├── util.py # Serialization, enum maps, blend formula, module loader
  223. └── tools/
  224. ├── session_tools.py # open/close/info (GPU quirks) + get_frame_overview
  225. ├── event_tools.py # list/get/set/search actions + find_draws
  226. ├── pipeline_tools.py # pipeline state, shader bindings, vertex inputs + get_draw_call_state
  227. ├── resource_tools.py # texture/buffer/resource enumeration
  228. ├── data_tools.py # save/read/pick/stats + read_texture_pixels + export_draw_textures, save_render_target, export_mesh
  229. ├── shader_tools.py # disassembly (fallback chain, search), reflection, cbuffer contents (filter)
  230. ├── advanced_tools.py # pixel history, post-VS data + diff_draw_calls (implications), analyze_render_passes, sample_pixel_region, debug_shader_at_pixel
  231. ├── performance_tools.py # get_pass_timing, analyze_overdraw, analyze_bandwidth, analyze_state_changes
  232. └── diagnostic_tools.py # diagnose_negative_values, diagnose_precision_issues, diagnose_reflection_mismatch, diagnose_mobile_risks
  233. ```
  234. ## License
  235. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.