让 AI 写你的视觉小说renpy-mcp一个让 Cursor 原生开发 Ren’Py 的 MCP 服务器你还在手动贴报错给 AI还在复制.rpy代码片段问 ChatGPT这篇文章介绍一个让 AI直接读懂、直接修改、直接编译验证你的 Ren’Py 项目的开源工具——renpy-mcp。仓库地址https://gitee.com/gdouage/renpy-mcp 欢迎 Star ⭐ 目录一、痛点Ren’Py 开发者为什么需要这个工具二、renpy-mcp 是什么三、15 个工具AI 能做什么四、核心能力详解五、5 分钟上手六、真实工作流演示七、技术架构八、为什么不用 ChatGPT 直接问九、项目信息与反馈一、痛点Ren’Py 开发者为什么需要这个工具如果你写过 Ren’Py大概率经历过这些场景报错看不懂Exception: Could not find return label、UnicodeDecodeError、SyntaxError……你只能把整段代码复制给 AIAI 猜了半天还猜错。改完不知道对不对AI 给你改了代码但你得自己点「启动项目」、自己跑 lint、自己看控制台报错、再复制回去问 AI——循环往复。文档查不到Ren’Py 中文文档分散在doc.renpy.cnAI 训练数据里未必有最新版问它Movie(channel...)怎么用它可能给你编一个不存在的 API。项目结构混乱几百个 label、几十个 screen谁调用了谁、哪个是死代码、哪个jump指向了不存在的标签——人肉看代码看到眼花。renpy-mcp 就是为了终结这个循环而生的。二、renpy-mcp 是什么renpy-mcp是一个 MCPModel Context Protocol服务器让 Cursor、Claude Desktop 等 AI Agent 成为 Ren’Py 的原生开发助手。一句话概括它让 AI 长出眼睛和手能直接读你的项目文件、查官方文档、改代码、跑编译、修 bug——全程不用你当传话筒。特性说明 AI 原生基于 MCP 协议Cursor / Claude 开箱即用 内置官方文档23 页 Ren’Py 中文文档打包在内离线可搜 15 个工具读代码 / 写代码 / 编译验证 / 自动修复 / 素材管理 / 文档搜索 跨平台Windows / macOS / Linux 全支持SDK 路径自动探测️ BOM 安全所有文件读写用utf-8-sig不会漏掉第一行的 label仓库地址https://gitee.com/gdouage/renpy-mcp三、15 个工具AI 能做什么renpy-mcp 给 AI 装上了 15 个工具分成 7 大类 读代码4 个工具能力list_labels列出全项目所有 labelrich 模式还能看参数、jump 目标、call 目标、是否 return 值read_script读取指定 label 的完整代码块find_references查找全项目中对某 label/screen 的所有 jump/call 引用list_definitions盘点所有角色、立绘、transform、screen、default、define 声明✏️ 写代码1 个工具能力exec_rpy往任意 .rpy 文件注入代码支持 8 种定位模式end/top/inside/after/before/replace/replace_all/自动建文件✅ 编译验证3 个工具能力compile_project编译 .rpy → .rpyc抓语法错误lint_project跑 Ren’Py lint 静态分析check_project一次跑完编译 lint 自动修复2 个工具能力auto_fix自动检测并修复 5 类常见问题修完重新编译验证list_fixers列出所有可用修复器 存档管理1 个工具能力manage_saveslist / clear / clear_stale清陈旧存档修复崩溃报错️ 素材管理2 个工具能力copy_asset拷贝图片/字体/音频到项目get_image_size获取图片尺寸算立绘定位用 文档搜索2 个工具能力search_docs搜索内置的 23 页 Ren’Py 中文官方文档list_doc_pages列出所有可用文档页面四、核心能力详解1. 内置官方文档AI 不再瞎编 API这是 renpy-mcp 最硬核的能力之一。23 页 Ren’Py 中文官方文档共 580KB被打包在src/renpy_mcp/docs/里包括quickstart.txt— 快速入门screens.txt— 界面语言77KBscreen_actions.txt— 界面行为60KBtransforms.txt— 变换和 ATL43KBgui.txt— GUI 定制化44KBmovie.txt— 视频播放audio.txt— 音频……共 23 个页面AI 调用search_docs(Movie)就能拿到官方文档里关于视频播放的真实段落不再凭训练记忆瞎编。离线可用不需要网络。2. auto_fix5 类常见 bug 一键修复Ren’Py 开发里有几个反复出现的经典坑renpy-mcp 能自动检测并修复修复器解决什么问题return_valuesRen’Py label 里写return True/False会崩自动改成$ _label_result True/Falsereturnmissing_fromcall xxx缺from子句会导致动态脚本报错自动补from _call_xxx_Nbom_normalize有中文的文件没 BOM 会漏掉第一行 label自动加 BOMmissing_labels检测 jump/call 到不存在的标签只报告stale_saves检测_reload-*/_tracesave-*残留存档只报告那个著名的Could not find return label报错很多时候就是return True 陈旧存档导致的renpy-mcp 能一次性解决。3. find_references重构前必查要改一个 label但不知道有多少地方调用了它find_references(arrow_round)一调用全项目所有jump arrow_round和call arrow_round全列出来还告诉你这个标签是否真的被定义了——没定义就是有 jump 指向了空气。五、5 分钟上手环境要求Python3.12Ren’Py SDK8.0Cursor 或 Claude Desktop安装gitclone https://gitee.com/gdouage/renpy-mcp.gitcdrenpy-mcp# 创建虚拟环境python-mvenv .venv# Windows.venv\Scripts\pipinstall-e.# macOS / Linux.venv/bin/pipinstall-e.配置 Cursor编辑~/.cursor/mcp.json不存在则创建{mcpServers:{renpy-mcp:{command:D:/absolute/path/to/renpy-mcp/.venv/Scripts/python.exe,args:[-m,renpy_mcp.server],env:{PYTHONPATH:D:/absolute/path/to/renpy-mcp/src,RENPY_SDK_PATH:D:/absolute/path/to/renpy-sdk}}}}配置 Claude Desktop编辑claude_desktop_config.json{mcpServers:{renpy-mcp:{command:/absolute/path/to/renpy-mcp/.venv/bin/python,args:[-m,renpy_mcp.server],env:{PYTHONPATH:/absolute/path/to/renpy-mcp/src,RENPY_SDK_PATH:/absolute/path/to/renpy-sdk}}}}macOS / Linux 用bin/python替代Scripts/python.exe。RENPY_SDK_PATH不设也会自动扫描常见路径。重启客户端重启 Cursor / Claude DesktopMCP 服务自动启动。现在对 AI 说「帮我看看这个项目的结构」它就会自己调用list_labels去读了。六、真实工作流演示场景 1接手一个陌生项目你帮我看看这个 RenPy 项目的结构 AI[调用 list_labels(richTrue)] [调用 list_definitions()] AI这个项目有 47 个 label入口是 start跳转到 chapter_01。 定义了 3 个角色ab、paopao、zhao12 个 screen5 个 transform……场景 2写一个视频播放功能你帮我加一个循环播放的背景视频 AI[调用 search_docs(Movie)] ← 查官方文档怎么用 Movie AI[调用 exec_rpy(...)] ← 根据文档写正确的代码 AI[调用 check_project()] ← 编译 lint 验证 AI编译通过lint 无报错视频已加到 fight_movie.rpy场景 3项目跑不起来你报错 Could not find return label怎么办 AI[调用 auto_fix()] ← 自动检测 5 类问题 AI发现 arrow_qte.rpy 里有 return True已自动修复 AI[调用 manage_saves(clear_stale)] ← 清掉陈旧存档 AI[调用 check_project()] ← 重新编译验证 AI修好了现在能正常跑了全程不用你复制一行代码、不用你点一次启动按钮。七、技术架构┌──────────────────────────────────────────────┐ │ AI Agent (Cursor / Claude) │ │ via MCP Protocol calls │ └──────────────────────┬───────────────────────┘ ▼ ┌──────────────────────────────────────────────┐ │ renpy-mcp Server │ │ (FastMCP, 15 tools) │ ├──────────┬──────────┬──────────┬──────────────┤ │ 读代码 │ 写代码 │ 验证修复 │ 文档知识库 │ ├──────────┴──────────┴──────────┴──────────────┤ │ 正则解析 .rpy │ BOM安全文件读写 │ subprocess 调 SDK │ └──────────────────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────┐ │ RenPy SDK (renpy.py) │ │ compile · lint · 项目文件 (.rpy/.rpyc) │ └──────────────────────────────────────────────┘技术栈MCP 协议 / FastMCP / Python 3.12 / Pillow / setuptools八、为什么不用 ChatGPT 直接问对比项直接问 ChatGPT用 renpy-mcp Cursor看项目结构你手动复制粘贴AI 自己读全项目视角查 APIAI 凭记忆可能编AI 搜内置官方文档准改代码AI 给你片段你手动贴AI 直接写进文件验证你自己点启动看报错AI 自己跑编译 lint修 bug你描述报错AI 猜AI 自己检测自己修循环次数来回十几轮一句话搞定一句话renpy-mcp 把 AI 从「顾问」变成了「实习生」——能看、能写、能跑、能改。九、项目信息与反馈 仓库gitee.com/gdouage/renpy-mcp 协议MIT 作者abbuibuibui✉️ 联系3244940576qq.com 文档来源doc.renpy.cn如果这个项目对你有帮助⭐ 去 Gitee 仓库 点个 Star 遇到问题提 Issue 欢迎 Pull Request你的一颗 Star是个人开发者继续更新的最大动力 ❤️