前言

作为图形程序员，你一定用过 RenderDoc。它是目前最流行的开源 GPU 帧捕获调试工具，支持 D3D11、D3D12、OpenGL、Vulkan 等主流图形 API。

但 RenderDoc 的使用门槛不低。面对一帧中成百上千个 Draw Call、复杂的 Pipeline 状态、数十个 Render Pass 和难以追踪的资源绑定，即使是经验丰富的图形工程师也需要花费大量时间逐一排查。

如果 AI 能直接读懂 RenderDoc 的帧捕获文件，帮你分析渲染问题，会怎样？

这就是 renderdoc-mcp 要做的事。

什么是 renderdoc-mcp

renderdoc-mcp 是一个 MCP（Model Context Protocol）服务器，它将 RenderDoc 的 Replay API 封装为 52 个标准化工具，通过 JSON-RPC 协议暴露给 AI 助手（Claude、Codex 等）。

简单来说：它让 AI 拥有了图形程序员的"眼睛"，可以打开 .rdc 捕获文件，浏览 Draw Call，检查 Pipeline 状态，查看 Shader 代码，导出渲染结果，甚至对比两帧之间的差异。

项目地址：github.com/JiaboLi-GitHub/renderdoc-mcp

核心能力

1. 帧捕获分析（27 个基础工具）

最基本的能力：打开一个 .rdc 文件，像图形工程师一样逐步分析。

  • Draw Call 浏览 —— 列出所有绘制调用，按 Pass 分组，跳转到任意事件

  • Pipeline 状态检查 —— 查看当前绑定的 Shader、Render Target、Viewport、混合状态等

  • Shader 反汇编 —— 获取任意 Shader 阶段的 HLSL/GLSL/SPIR-V 反汇编代码

  • 资源检查 —— 列出所有纹理、Buffer、Shader 资源，查看详细信息

  • 像素级调试 —— Pixel History、像素拾取、Shader 单步调试

  • 渲染结果导出 —— 将 Render Target、纹理导出为 PNG 图片

典型的 AI 分析流程：

open_capture → list_draws → goto_event → get_pipeline_state
→ get_shader → export_render_target → 给出分析结论

2. 实时帧捕获

不只是分析已有的 .rdc 文件 —— renderdoc-mcp 还能注入正在运行的图形应用程序，实时捕获一帧并立即开始分析：

capture_frame("MyGame.exe") → 自动注入 → 捕获 → 打开 → 分析

这意味着你可以对着 AI 说："帮我抓一帧看看现在画面为什么不对"，AI 就能直接操作。

3. 帧对比引擎（Diff Engine）

这是 renderdoc-mcp 最强大的特性之一。它可以同时打开两个 .rdc 文件，从 6 个维度进行深度对比：

维度 说明
Draw Call 对比 使用 LCS 算法对齐两帧的 Draw Call 序列，标注新增/删除/修改
Pipeline 对比 逐项比较 Shader、混合状态、光栅化状态等
资源对比 比较纹理/Buffer 数量、格式、尺寸变化
统计对比 比较三角形数量、Draw Call 数量等性能指标
帧缓冲对比 像素级比较最终渲染结果
Pass 结构对比 比较渲染 Pass 的组织方式

应用场景：版本回归检测、性能对比、渲染正确性验证。

4. Shader 热编辑

在不重启应用的情况下，直接编译和替换 Shader：

get_shader → 修改代码 → shader_build → shader_replace → 查看效果

AI 可以帮你快速定位 Shader 中的问题，提出修改建议，甚至直接替换测试。

5. CI 断言框架

为持续集成设计的 5 个断言工具，让 GPU 渲染也能像普通代码一样进行自动化测试：

  • assert_pixel —— 验证指定像素的颜色值

  • assert_state —— 验证 Pipeline 状态是否符合预期

  • assert_image —— 图像级别的渲染结果比较

  • assert_count —— 验证资源/Draw Call 数量

  • assert_clean —— 检测未使用的 Render Target 等潜在问题

6. 渲染 Pass 分析

自动识别渲染 Pass 结构，分析每个 Pass 的：

  • Attachment（颜色/深度目标）

  • 统计信息（Draw 数量、三角形数量）

  • 资源依赖关系（DAG 图）

  • 未使用的 Render Target 检测

架构设计

项目由 3 个静态库 + 2 个可执行文件组成，依赖关系如下：

┌──────────────────────────────────────────────────────┐
│          AI 客户端 (Claude / Codex / 其他)             │
│                    或 Shell / CI                      │
└───────────┬──────────────────────────┬───────────────┘
            │ JSON-RPC (stdio)         │ CLI args
            ▼                          ▼
  ┌──────────────────┐       ┌──────────────────┐
  │ renderdoc-mcp.exe│       │ renderdoc-cli.exe│
  └────────┬─────────┘       └────────┬─────────┘
           │                          │
           ▼                          │
  ┌──────────────────┐                │
  │ renderdoc-mcp-lib│                │
  │  (工具桥接层)     │                │
  │  52 个 Tool 实现  │                │
  └───┬──────────┬───┘                │
      │          │                    │
      ▼          ▼                    │
┌───────────┐ ┌─────────────┐        │
│  mcp-proto│ │renderdoc-core│◄───────┘
│ (协议层)   │ │  (业务逻辑)  │
│ McpServer │ │ Session      │
│ToolRegistry│ DiffSession  │
│Serialization Events       │
│           │ │ Pipeline ... │
│ 不依赖     │ │              │
│ RenderDoc │ │              │
└───────────┘ └──────┬───────┘
                     │
                     ▼
            ┌─────────────────┐
            │RenderDoc Replay  │
            │      API         │
            │(renderdoc.dll)   │
            └─────────────────┘

这个架构有几个关键设计：

  • proto 与 core 并列，互不依赖 —— renderdoc-mcp-proto 只包含 MCP 协议处理（McpServer、ToolRegistry、序列化），完全不依赖 RenderDoc；renderdoc-core 只包含 GPU 调试业务逻辑，完全不依赖 MCP 协议。两者通过 renderdoc-mcp-lib 桥接

  • CLI 直达 Core —— renderdoc-cli 直接链接 renderdoc-core，不经过任何 MCP 协议层，是最短路径

  • 声明式工具注册 —— ToolRegistry 提供自动参数校验和 JSON-RPC 错误码映射，工具定义与协议处理解耦

  • Session 隔离 —— 主分析 Session 和 Diff Session 独立共存，互不干扰

  • 多 API 支持 —— D3D11、D3D12、OpenGL、Vulkan 均可分析

技术栈

组件 技术选型
语言 C++17 (MSVC)
构建 CMake 3.16+
JSON nlohmann/json v3.11.3
协议 JSON-RPC 2.0 over stdio (MCP 2025-03-26)
GPU 调试 RenderDoc Replay API
测试 Google Test
图像编码 stb_image
平台 Windows x64

实际使用效果

场景一：排查渲染异常

你： "帮我打开这个 rdc 文件，画面右上角有一块黑色区域，帮我分析原因。"

AI： 打开文件 → 浏览 Draw Call → 定位到可疑的全屏 Pass → 检查 Pipeline 状态 → 发现 Scissor Rect 配置错误 → 导出前后对比图 → 给出修复建议

场景二：版本回归对比

你： "这两个版本的帧捕获，帮我对比一下有什么变化。"

AI： diff_open 同时加载两帧 → diff_summary 概览差异 → diff_draws 发现新增了 3 个 Draw Call → diff_pipeline 检查新 Draw 的状态 → diff_framebuffer 确认像素级差异 → 总结回归点

场景三：CI 自动化验证

你： "在 CI 流水线中，每次构建后自动验证渲染结果是否正确。"

AI： capture_frame 抓取一帧 → assert_pixel 验证关键像素 → assert_count 验证 Draw Call 数量 → assert_clean 检查资源浪费 → 输出通过/失败报告

快速上手

安装

从 GitHub Releases 下载预编译的 Windows x64 包，解压即用。包含：

bin/
  renderdoc-mcp.exe    # MCP 服务器
  renderdoc-cli.exe    # CLI 工具
  renderdoc.dll        # RenderDoc 运行时
  renderdoc.json       # API 定义

配置 Claude Code

在 Claude Code 的 MCP 设置中添加：

{
  "mcpServers": {
    "renderdoc": {
      "command": "path/to/bin/renderdoc-mcp.exe"
    }
  }
}

从源码构建

git clone https://github.com/JiaboLi-GitHub/renderdoc-mcp.git
cd renderdoc-mcp
cmake -B build -DRENDERDOC_DIR=D:/renderdoc/renderdoc
cmake --build build --config Release

为什么做这个项目

图形编程的调试体验一直是痛点。RenderDoc 虽然强大，但信息量巨大，分析过程繁琐。MCP 协议的出现提供了一个标准化的 AI-工具桥接方案，让我们可以把 RenderDoc 的专业能力"翻译"成 AI 能理解和操作的语言。

renderdoc-mcp 的目标不是替代 RenderDoc 的 GUI，而是在它之上叠加一层 AI 驱动的分析能力：

  • 对于新手，AI 可以引导你理解每一帧在做什么

  • 对于老手，AI 可以帮你快速筛选、对比、定位问题

  • 对于团队，CI 断言框架让渲染质量成为可量化的指标

项目状态

当前版本 v0.3.0，包含 52 个 MCP 工具，覆盖从基础分析到高级对比的完整工作流。项目开源，欢迎贡献。

版本 里程碑
v0.1.0 27 个基础工具，Session 管理，CLI
v0.2.0 实时帧捕获
v0.3.0 Shader 热编辑、帧对比引擎、Pass 分析、CI 断言

写在最后

GPU 调试正在进入 AI 时代。renderdoc-mcp 是这个方向上的一次尝试 —— 把图形程序员的经验和工具链与大语言模型的理解能力结合起来。

如果你是图形程序员，欢迎试用并反馈；如果你对 MCP 协议或 AI+DevTools 方向感兴趣，欢迎一起探讨。

GitHub： github.com/JiaboLi-GitHub/renderdoc-mcp

# 人工智能 # 图形渲染
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

AtomGit 首发开源｜光轮智能发布全球首个十万小时级全模态人类行为开源数据集 EgoSuite-Open100K

avatar AtomGit开源社区
cover

构筑赋能金融行业应用 Agent｜20 强决战北京，一场金融 Agent 的硬核答卷

avatar AtomGit开源社区
cover

AtomCode 全新上线万亿代码模型 LongCat-2.0。限时 7 天免费体验！

avatar AtomGit开源社区