让 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，大概率经历过这些场景：

1. 报错看不懂：Exception: Could not find return label、UnicodeDecodeError、SyntaxError……你只能把整段代码复制给 AI，AI 猜了半天还猜错。
2. 改完不知道对不对：AI 给你改了代码，但你得自己点「启动项目」、自己跑 lint、自己看控制台报错、再复制回去问 AI——循环往复。
3. 文档查不到：Ren’Py 中文文档分散在doc.renpy.cn，AI 训练数据里未必有最新版，问它Movie(channel=...)怎么用，它可能给你编一个不存在的 API。
4. 项目结构混乱：几百个 label、几十个 screen，谁调用了谁、哪个是死代码、哪个jump指向了不存在的标签——人肉看代码看到眼花。

renpy-mcp 就是为了终结这个循环而生的。

二、renpy-mcp 是什么

renpy-mcp是一个 MCP（Model Context Protocol）服务器，让 Cursor、Claude Desktop 等 AI Agent 成为 Ren’Py 的原生开发助手。

一句话概括：它让 AI 长出眼睛和手，能直接读你的项目文件、查官方文档、改代码、跑编译、修 bug——全程不用你当传话筒。

仓库地址：https://gitee.com/gdouage/renpy-mcp

三、15 个工具，AI 能做什么

renpy-mcp 给 AI 装上了 15 个工具，分成 7 大类：

🔍 读代码（4 个）

✏️ 写代码（1 个）

✅ 编译验证（3 个）

🩺 自动修复（2 个）

💾 存档管理（1 个）

🖼️ 素材管理（2 个）

📖 文档搜索（2 个）

四、核心能力详解

1. 内置官方文档，AI 不再瞎编 API

这是 renpy-mcp 最硬核的能力之一。23 页 Ren’Py 中文官方文档（共 580KB）被打包在src/renpy_mcp/docs/里，包括：

• quickstart.txt— 快速入门
• screens.txt— 界面语言（77KB）
• screen_actions.txt— 界面行为（60KB）
• transforms.txt— 变换和 ATL（43KB）
• gui.txt— GUI 定制化（44KB）
• movie.txt— 视频播放
• audio.txt— 音频
• ……共 23 个页面

AI 调用search_docs("Movie")就能拿到官方文档里关于视频播放的真实段落，不再凭训练记忆瞎编。离线可用，不需要网络。

2. auto_fix：5 类常见 bug 一键修复

Ren’Py 开发里有几个反复出现的经典坑，renpy-mcp 能自动检测并修复：

那个著名的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.12+
• Ren’Py SDK8.0+
• Cursor 或 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 Desktop，MCP 服务自动启动。现在对 AI 说「帮我看看这个项目的结构」，它就会自己调用list_labels去读了。

六、真实工作流演示

场景 1：接手一个陌生项目

你：帮我看看这个 Ren'Py 项目的结构 AI：[调用 list_labels(rich=True)] [调用 list_definitions()] AI：这个项目有 47 个 label，入口是 start，跳转到 chapter_01。 定义了 3 个角色（ab、paopao、zhao），12 个 screen，5 个 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 │ └──────────────────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────┐ │ Ren'Py SDK (renpy.py) │ │ compile · lint · 项目文件 (.rpy/.rpyc) │ └──────────────────────────────────────────────┘

技术栈：MCP 协议 / FastMCP / Python 3.12+ / Pillow / setuptools

八、为什么不用 ChatGPT 直接问

一句话：renpy-mcp 把 AI 从「顾问」变成了「实习生」——能看、能写、能跑、能改。

九、项目信息与反馈

如果这个项目对你有帮助：

1. ⭐ 去 Gitee 仓库 点个 Star
2. 🐛 遇到问题提 Issue
3. 🔁 欢迎 Pull Request

你的一颗 Star，是个人开发者继续更新的最大动力 ❤️