renpy-mcp
Serves as an AI-native development assistant for Ren'Py visual novel projects, providing tools to read .rpy scripts (list labels, read label code blocks, find jump/call references, list character/sprite/screen definitions), inject code into .rpy files with 8 positioning modes, compile and lint projects via the Ren'Py SDK with structured error reports, automatically fix common issues (return values, missing from clauses, BOM inconsistency, missing labels, stale saves), manage save files, copy image/font/audio assets and get image dimensions, check translation coverage and language-picker configuration across game/tl language folders, search bundled Ren'Py Chinese documentation offline, and run arbitrary Ren'Py CLI subcommands (compile/lint/translate).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@renpy-mcp check my Ren'Py project for errors and fix them"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ð® renpy-mcp â Ren'Py AI åçåŒå婿
è¯èš / Languages: ç®äœäžæ | English
äžäžª MCPïŒModel Context ProtocolïŒæå¡åšïŒè®© AI AgentïŒCursorãClaude çïŒæäžº Ren'Py è§è§å°è¯ŽçåçåŒå婿ââ读代ç ãå代ç ãæ¥å®æ¹ææ¡£ãèªåšä¿®å€ãçŒè¯éªè¯ïŒå šæµçšéç¯ã
åºäº FastMCP æå»ºïŒå 眮 Ren'Py äžæå®æ¹ææ¡£ïŒ23 页 / 580KBïŒïŒè·šå¹³å°æ¯æ Windows / macOS / Linuxã
â åŠæè¿äžªé¡¹ç®åž®å°äœ ïŒæ¬¢è¿å»ä»åºç¹äžª Star æ¯æäžäžïœ ð https://gitee.com/gdouage/renpy-mcp äœ çäžé¢æïŒæ¯äžªäººåŒåè ç»§ç»æŽæ°çæå€§åšå â€ïž
ä»åº | |
åè®® | |
äœè | abbuibuibui |
èç³» | |
ææ¡£æ¥æº |
ð 项ç®ä»ç»
Ren'Py 没æå
眮çŒèŸåšïŒåŒåè
æåšå .rpy ææ¬æä»¶åç¹ãå¯åšé¡¹ç®ãæµè¯ãè¿äžª MCP 让 AI çŽæ¥çè§£ Ren'Py 项ç®ç»æââäžçšäœ æåšèŽŽæ¥éïŒAI èªå·±å°±èœè¯»ä»£ç ãæ¥ææ¡£ãæ¹ä»£ç ãçŒè¯éªè¯ãèªåšä¿® bugã
èœå | 诎æ |
读代ç | ååºå šéš label / 读åæå® label èæ¬ / çç¹è§è²ç«ç» screen 声æ / æ¥æŸ jump-call è°çšå ³ç³» |
æ¥ææ¡£ | å 眮 23 页 Ren'Py äžæå®æ¹ææ¡£ïŒå ³é®è¯æçŽ¢è¿åçžå ³æ®µèœïŒçŠ»çº¿å¯çš |
å代ç | åŸä»»æ .rpy æä»¶æ³šå ¥ä»£ç ïŒ8 ç§å®äœæš¡åŒïŒïŒèªåšå»ºæä»¶ïŒä¿ç BOM |
çŒè¯éªè¯ | çŒè¯ + lint äžæ¬¡è·å®ïŒè¿åç»æåéè¯¯ïŒæä»¶å + è¡å· + æ¶æ¯ïŒ |
èªåšä¿®å€ | æ£æµå¹¶ä¿®å€ 5 类垞è§é®é¢ïŒ |
ç¿»è¯æ£æ¥ | ååºææè¯èš / æ·±åºŠæ£æ¥ç¿»è¯èŠçïŒæ"åªæå笊䞲翻è¯ã猺åç¿»è¯"çéé» bugïŒ/ æ ¡éªè¯èšéæ©åšé 眮 |
åæ¡£ç®¡ç | ååº / æž
é€ / æž
é€éæ§åæ¡£ïŒä¿®å€ |
çŽ æç®¡ç | æ·èŽåŸç / åäœ / é³é¢å°é¡¹ç®ïŒè·ååŸç尺寞ç®ç«ç»å®äœ |
éçš CLI | çŽæ¥è·ä»»æ Ren'Py ååœä»€ïŒcompile/lint/translate çïŒïŒèªå®ä¹è¶ æ¶ |
è·šå¹³å° | Windows / macOS / Linux å šæ¯æïŒSDK è·¯åŸèªå𿢿µ |
æ žå¿æµçšïŒ
æ¥ææ¡£(search_docs) â 读代ç (list_labels) â å代ç (exec_rpy) â çŒè¯éªè¯(check_project) â èªåšä¿®å€(auto_fix)Related MCP server: mcdev-mcp
ðïž é¡¹ç®æ¶æ
ââââââââââââââââââââââââââââââââââââââââââââââââ
â AI Agent (Cursor / Claude) â
â éè¿ MCP åè®®è°çš â
ââââââââââââââââââââââââ¬ââââââââââââââââââââââââ
â
âŒ
ââââââââââââââââââââââââââââââââââââââââââââââââ
â renpy-mcp Server â
â (FastMCP, 19 䞪工å
·) â
ââââââââââââ¬âââââââââââ¬âââââââââââ¬âââââââââââââââ€
â 读代ç â å代ç â éªè¯ä¿®å€ â ææ¡£ç¥è¯åº â
â (4 tools)â (1 tool) â (5 tools)â (2 tools) â
ââââââââââââŽâââââââââââŽâââââââââââŽâââââââââââââââ€
â ç¿»è¯æ£æ¥(3) éçšCLI(1) åæ¡£(1) çŽ æ(2) â
âââââââââââââââââââââââââââââââââââââââââââââââââ€
â åºå±èœå â
â âââââââââââ ââââââââââââ âââââââââââââââââ â
â â æ£åè§£æ â â æä»¶è¯»å â â subprocess â â
â â .rpyæä»¶ â â BOMå®å
š â â è°çšRen'Py SDK â â
â âââââââââââ ââââââââââââ âââââââââââââââââ â
ââââââââââââââââââââââââââââââââââââââââââââââââ
â
âŒ
ââââââââââââââââââââââââââââââââââââââââââââââââ
â Ren'Py SDK (renpy.py) â
â compile · lint · é¡¹ç®æä»¶ (.rpy/.rpyc) â
ââââââââââââââââââââââââââââââââââââââââââââââââç®åœç»æïŒ
renpy-mcp/
âââ src/renpy_mcp/
â âââ server.py # MCP æå¡å
¥å£ + å·¥å
·æ³šå
â âââ project.py # æ çŸè§£æïŒlist_labels / read_script / find_references / list_definitions
â âââ executor.py # ä»£ç æ³šå
¥ïŒexec_rpyïŒ8ç§å®äœ + CJKåäœïŒ
â âââ build.py # çŒè¯éªè¯ïŒcompile / lint / check_project / manage_saves / run_renpy_command
â âââ fixer.py # èªåšä¿®å€ïŒauto_fixïŒ5类修å€åšïŒ
â âââ assets.py # çŽ æç®¡çïŒcopy_asset / get_image_size
â âââ translation.py # ç¿»è¯æ£æ¥ïŒlist_translations / check_translation / check_language_picker
â âââ docs_search.py # ææ¡£æçŽ¢ïŒsearch_docs / list_doc_pages
â âââ config.py # SDK è·¯åŸé
眮ïŒè·šå¹³å°èªå𿢿µïŒ
â âââ docs/ # å
çœ®å®æ¹ææ¡£ïŒ23页ïŒ580KBïŒ
â âââ quickstart.txt # å¿«éå
¥éš
â âââ screens.txt # çé¢è¯èšïŒ77KBïŒ
â âââ screen_actions.txt # çé¢è¡äžºïŒ60KBïŒ
â âââ transforms.txt # 忢åATLïŒ43KBïŒ
â âââ gui.txt # GUIå®å¶åïŒ44KBïŒ
â âââ ... # å
±23äžªææ¡£é¡µé¢
âââ AI_GUIDE.md # AI Agent æäœè§è
âââ CHANGELOG.md # åæŽæ¥å¿
âââ pyproject.toml # å
é
眮
âââ LICENSE # MIT åè®®
âââ README.md # äžæïŒé»è®€ïŒGitee éŠé¡µå±ç€ºïŒ
âââ README.en.md # Englishð ïž ææ¯æ
å±çº§ | ææ¯ |
åè®® | MCP (Model Context Protocol) |
æ¡æ¶ | FastMCP |
è¯èš | Python 3.12+ |
ææ¡£è§£æ | Python æ ååº html.parser |
åŸçå€ç | Pillow |
æå»ºç³»ç» | setuptools |
SDK è°çš | subprocess è°çš Ren'Py SDK |
ð å¿«éåŒå§
1. ç¯å¢èŠæ±
Python 3.12+
Ren'Py SDK 8.0+ïŒçšäºçŒè¯å lintïŒ
æ¯æ MCP ç AI 客æ·ç«¯ïŒCursorãClaude Desktop çïŒ
2. è·å代ç
git clone https://gitee.com/gdouage/renpy-mcp.git
cd renpy-mcp3. å®è£
# å建èæç¯å¢
python -m venv .venv
# Windows
.venv\Scripts\pip install -e .
# macOS / Linux
.venv/bin/pip install -e .4. é 眮 MCP 客æ·ç«¯
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æåäœ ç Ren'Py SDK ç®åœïŒåŠrenpy-8.5.3-sdkïŒãæªè®Ÿçœ®æ¶æå¡åšäŒèªåšæ«æåžžè§è·¯åŸã
5. éå¯å®¢æ·ç«¯ ð¬
éå¯ Cursor / Claude DesktopïŒMCP æå¡èªåšå¯åšãAI ç°åšå¯ä»¥çŽæ¥æäœäœ ç Ren'Py 项ç®ã
ð¡ 19 äžªå·¥å ·äžè§
读代ç ïŒ4 䞪ïŒ
å·¥å · | åèœ |
| ååºå šé¡¹ç®ææ labelïŒå¯é rich æš¡åŒïŒåæ°ãjump ç®æ ãcall ç®æ ãè¿ååŒïŒ |
| 读åæå® label ç宿Žä»£ç åïŒBOM å®å šïŒ |
| æ¥æŸå šé¡¹ç®äžå¯¹æ label/screen çææ jump/call åŒçš |
| çç¹ææè§è²ãç«ç»ãtransformãscreenãdefaultãdefine 声æ |
å代ç ïŒ1 䞪ïŒ
å·¥å · | åèœ |
| åŸä»»æ .rpy æä»¶æ³šå ¥ä»£ç ïŒ8 ç§å®äœïŒend/top/inside/after/before/replace/replace_all/èªåšå»ºæä»¶ïŒ |
çŒè¯éªè¯ïŒ3 䞪ïŒ
å·¥å · | åèœ |
| çŒè¯ .rpy â .rpycïŒæè¯æ³é误ïŒå¯åŒºå¶æž çŒåïŒ |
| è· Ren'Py lint éæåæïŒæ¥æªå®ä¹åéãäžå¯èŸŸä»£ç çïŒ |
| äžæ¬¡è·å®çŒè¯ + lintïŒçŒè¯äžè¿åè·³è¿ lintïŒ |
èªåšä¿®å€ïŒ2 䞪ïŒ
å·¥å · | åèœ |
| èªå𿣿µå¹¶ä¿®å€ 5 ç±»é®é¢ïŒä¿®å€åéæ°çŒè¯éªè¯ |
| ååºææå¯çšä¿®å€åš |
auto_fix æ¯æç 5 类修å€ïŒ
ä¿®å€åš | ç±»å | åä»ä¹ |
| æ¹ä»£ç |
|
| æ¹ä»£ç |
|
| æ¹ä»£ç | æ CJK å 容çæä»¶å BOMïŒæ²¡ CJK çå» BOM |
| åªæ¥å | æ£æµ jump/call å°äžååšç label |
| åªæ¥å | æ£æµ |
åæ¡£ç®¡çïŒ1 䞪ïŒ
å·¥å · | åèœ |
| listïŒååºåæ¡£ïŒ/ clearïŒå šå ïŒ/ clear_staleïŒæž éæ§åæ¡£ïŒ |
çŽ æç®¡çïŒ2 䞪ïŒ
å·¥å · | åèœ |
| æ·èŽåŸç/åäœ/é³é¢å°é¡¹ç®ïŒèªåšè¡¥ |
| è·ååŸç尺寞ïŒç®ç«ç»å®äœ transform çšïŒ |
ææ¡£æçŽ¢ïŒ2 䞪ïŒ
å·¥å · | åèœ |
| æçŽ¢å 眮 Ren'Py äžæå®æ¹ææ¡£ïŒ23 页ïŒïŒè¿åçžå ³æ®µèœ |
| ååºææå¯çšææ¡£é¡µé¢ |
ç¿»è¯æ£æ¥ïŒ3 䞪ïŒ
å·¥å · | åèœ |
| ååº |
| æ·±åºŠæ£æ¥ç¿»è¯èŠçãæ žå¿æ£æµïŒæç¿»è¯æä»¶åªæ |
| æ ¡éª |
éçš CLIïŒ1 䞪ïŒ
å·¥å · | åèœ |
| çŽæ¥è·ä»»æ Ren'Py CLI ååœä»€ïŒcompile / lint / translate / rtc çïŒïŒèªå®ä¹è¶
æ¶ãçšäºçæ/å·æ°ç¿»è¯æä»¶ïŒ |
ð å žåå·¥äœæµ
åºæ¯ 1ïŒæ¥æéç项ç®
list_labels(rich=True) â çå
šé¡¹ç®ç»æå跳蜬å
³ç³»
list_definitions() â çæåªäºè§è²/ç«ç»/screen
read_script("start") â 读å
¥å£æ çŸä»£ç
find_references("chapter_01") â çè°è°çšäºè¿äžªæ çŸåºæ¯ 2ïŒåæ°åèœ
search_docs("Movie") â æ¥å®æ¹ææ¡£æä¹ææŸè§é¢
exec_rpy(...) â æ ¹æ®ææ¡£åæ£ç¡®ç代ç
check_project(force=True) â çŒè¯ + lint éªè¯åºæ¯ 3ïŒéå°æ¥éèªåšä¿®å€
auto_fix() â èªå𿣿µå¹¶ä¿®å€ 5 类垞è§é®é¢
manage_saves("clear_stale") â æž
æå¯ŒèŽåŽ©æºçéæ§åæ¡£åºæ¯ 4ïŒéæåæ£æ¥åœ±åèåŽ
find_references("arrow_round") â çè°è°äºå®ïŒ12 å€ïŒ
find_references("chapter_03") â æ²¡äººè° = æ»ä»£ç
find_references("typo_label") â defined=False = æ jump æåäžååšçæ çŸåºæ¯ 5ïŒå€è¯èšç¿»è¯ææ¥ïŒ"éäº English è¿æ¯äžæ"ïŒ
list_translations() â çæåªäºè¯èšãæ¯äžªè¯èšç¿»è¯äºå€å°
check_translation("english") â æ"åªæå笊䞲翻è¯çŒºåç¿»è¯"çéé» bug
+ éå€ old å笊䞲 + çŒºç¿»è¯æä»¶çæºæä»¶
check_language_picker() â æ ¡éª"English"æé®æ¯åŠè¯¯çš Language(None)
run_renpy("translate",["english"]) â éæ°çæåç¿»è¯éªšæ¶ç宿¡äŸïŒäžäžªç« èçç¿»è¯æä»¶è¢«åæäºåç¬Šäž²ç¿»è¯æ ŒåŒïŒ
old/newïŒïŒçŒè¯äžæ¥éïŒ äœæžžæé对è¯å 𿝿ºè¯èšââå 䞺 Ren'Py 对è¯åªè®€åç¿»è¯ãcheck_translationäžçŒå°±èœæå°ã
ð¡ 讟计诎æ
ææ¡£çŠ»çº¿å¯çšïŒ23 页宿¹ææ¡£æå åš
src/renpy_mcp/docs/ïŒäžéèŠçœç»BOM å®å šïŒæææä»¶è¯»å䜿çš
utf-8-sigïŒäžäŒæŒæç¬¬äžè¡ç labelCJK åäœå¯éïŒ
exec_rpyçauto_cjk_fonté»è®€å ³éïŒäžé黿¹ gui.rpySDK èªå𿢿µïŒæªè®Ÿ
RENPY_SDK_PATHæ¶èªåšæ«æåžžè§è·¯åŸïŒæä¿®æ¹æ¶éŽåææ°ä¿®æ¹ç±»ä¿®å€åšä¿ç BOMïŒåå ¥æ¶æ£æµåæä»¶æ¯åŠæ BOMïŒæåä¿ç
åªè¯»æ£æ¥åšäžæ¹ä»£ç ïŒ
missing_labelsåstale_savesåªæ¥åäžä¿®æ¹çŒè¯äžå¡æ»ïŒsubprocess å
stdin=DEVNULLïŒè¶ æ¶å¯çšRENPY_SDK_PATHç¯å¢åéæçRENPY_MCP_TIMEOUTè°æŽïŒé»è®€ 180sïŒç¿»è¯æ£æ¥åªè¯»ïŒ
check_translation/check_language_pickeråªåææ¥åïŒç»äžæ¹äœ çç¿»è¯æä»¶å¯¹è¯è¯å«ç²ŸåïŒç»è®¡æºæä»¶å¯¹è¯æ¶åªè®€å·²å®ä¹ç
CharacteråéåïŒäžäŒæcolor "#fff"ãkey "K_SPACE"è¿ç±»çé¢/æ ·åŒå±æ§è¡è¯¯å€æå¯¹è¯
ð¬ åéŠäžèŽ¡ç®
åŠæè¿äžªé¡¹ç®å¯¹äœ æåž®å©ïŒææïŒ
â å»ä»åºç¹äžª StarïŒrenpy-mcp
ð éå°é®é¢æ Issue
âïž æ³äº€æµå¯åé®ä»¶ïŒ3244940576@qq.comïŒäœè ïŒabbuibuibuiïŒ
乿¬¢è¿æäº€ Pull RequestïŒè¯·å è¯Žææ¹åšç®çäžæµè¯æ¹åŒïŒïœ
ð 讞å¯è¯
æ¬é¡¹ç®åºäº MIT License åŒæºã
Copyright (c) 2026 abbuibuibuiAvailable Tools
19 toolstool_auto_fixA
Detect and repair common Ren'Py issues automatically, then re-compile to verify.
Runs a set of safe, targeted fixers on a project. Each fixer handles a specific class of problem. After applying fixes, re-compiles to verify the project still builds.
Available fixers:
- "return_values": Convert return True/False in labels to global
variable + bare return (fixes 'Could not find return label' errors)
- "missing_from": Add from _call_<label>_<N> to call statements
missing the from clause (fixes save/load issues)
- "bom_normalize": Ensure .rpy files with CJK content have consistent BOM
- "missing_labels": Detect jump/call to undefined labels (report only)
- "stale_saves": Detect stale save files that may cause runtime errors
Args: project_path: Absolute path to the Ren'Py project root directory. fixes: List of fixer names to run. If None, runs all fixers.
Returns: dict with {ok, applied, skipped, applied_count, skipped_count, compile_before, compile_after}.
Inputs: project_path (required), fixes.
tool_check_language_pickerA
Verify the language picker in screens.rpy against tl/ folders and config.language.
Catches the common misconfiguration where the "English" button is wired to
Language(None) (show source text) instead of Language("english")
(apply the english translation) -- when the source language is not
English, Language(None) shows the source (e.g. Chinese) text, so clicking
"English" appears to do nothing.
Also detects: dead buttons pointing at tl/ folders that don't exist, and missing buttons for translations that do exist.
Args: project_path: Absolute path to the Ren'Py project root directory.
Returns: dict with {ok, source_language, available_languages, buttons, issues}.
Inputs: project_path (required).
tool_check_projectA
Run compile then lint in one call. Returns combined structured result.
If compile fails, returns immediately with compile errors (no point linting broken syntax). If compile passes, runs lint and merges warnings.
Args: project_path: Absolute path to the Ren'Py project root directory. force: If True, clear .rpyc cache before compiling (default True).
Returns: dict with {ok, compile_errors, lint_warnings, raw_output}.
Inputs: project_path (required), force.
tool_check_translationA
Deep-check translation coverage. Catches silent dialogue-not-translated bugs.
The most important check: a translation file that ONLY contains
translate <lang> strings: (old/new pairs) but NO translate <lang> <hash>: block translations. Ren'Py does NOT translate say-statement
dialogue via string translation -- only block translation does that. A
string-only file leaves dialogue in the source language with no error.
Also detects: duplicate old strings (runtime error risk), untranslated
block translations (active line still equals the source comment), and
source files with dialogue that have no translation file at all.
Args: project_path: Absolute path to the Ren'Py project root directory. language: Language code to check (e.g. "english"). If None, checks all languages found under game/tl/.
Returns: dict with {ok, source_language, languages: [{code, issues, summary}]}. Issues have severity "error" | "warning" | "info".
Inputs: project_path (required), language.
tool_compile_projectA
Compile a Ren'Py project (validate syntax).
Runs Ren'Py's compiler on all .rpy files. Returns structured errors with file paths and line numbers if compilation fails.
Args: project_path: Absolute path to the Ren'Py project root directory. force: If True, clear .rpyc cache before compiling (to pick up file changes).
Returns: dict with {ok: bool, errors: [{file, line, message}], raw_output: str}.
Inputs: project_path (required), force.
tool_copy_assetA
Copy an asset file (image, font, audio) into a Ren'Py project.
Copies a file from anywhere on the system into the project's game directory. Automatically creates subdirectories as needed. Auto-prefixes 'game/' to dest if not already present.
Args: project_path: Absolute path to the Ren'Py project root directory. source: Absolute path to the source file on disk. dest: Relative path within project (e.g. "images/char_happy.png").
Returns: dict with {ok, message, dest_path}.
Inputs: dest (required), source (required), project_path (required).
tool_exec_rpyA
Inject arbitrary Ren'Py code into a project file.
This is the universal "escape hatch" tool. Use it to write any Ren'Py script code: define characters, declare images, create screens, add dialogue to labels, write init python blocks, etc.
If the target file doesn't exist, it will be auto-created. BOM is preserved when overwriting an existing file that has one.
Args: project_path: Absolute path to the Ren'Py project root directory. file: Target .rpy file, relative to project_path (e.g. "game/script.rpy"). code: Raw Ren'Py script code to inject. position: Where to place the code: - "end": Append at end of file (default) - "top": Prepend at start of file - "inside:": Insert at end of a label block - "after:": Insert right after a label block ends - "before:": Insert right before a label definition - "replace:<old_text>": Replace first occurrence of old_text with code - "replace_all:<old_text>": Replace ALL occurrences of old_text with code auto_compile: Whether to run compile_project after writing (default True). auto_cjk_font: If True and code contains CJK text, auto-configure a CJK font in gui.rpy. Defaults to False to avoid surprising side effects.
Returns: dict with {ok, message, compile_result, font_setup?, cjk_warning?}.
Inputs: code (required), file (required), project_path (required), position, +2 more.
tool_find_referencesA
Find all jump/call references to a label or screen across the project.
Parses jump and call statements to build a reference map. Useful for refactoring (find all callers before renaming), detecting dead code (labels never jumped/called), and catching missing targets (jump to a label that doesn't exist).
Args: project_path: Absolute path to the Ren'Py project root directory. name: The label or screen name to search for (e.g. "arrow_round").
Returns: dict with {name, defined, definition, is_screen, callers, caller_count}.
Inputs: name (required), project_path (required).
tool_get_image_sizeA
Get dimensions and format of an image file.
Useful for calculating correct sprite positioning transforms. Supports absolute paths or paths relative to project_path.
Args: project_path: Absolute path to the Ren'Py project root directory. image_path: Path to image file (absolute, or relative to project_path).
Returns: dict with {ok, width, height, format, file_size}.
Inputs: image_path (required), project_path (required).
tool_lint_projectA
Run Ren'Py lint on a project (static analysis).
Checks for undefined variables, unreachable code, missing labels, etc. More thorough than compile but may produce false positives.
Args: project_path: Absolute path to the Ren'Py project root directory.
Returns: dict with {ok: bool, warnings: [{file, line, message}], raw_output: str}.
Inputs: project_path (required).
tool_list_definitionsA
Inventory all declarations in a Ren'Py project.
Scans all .rpy files and returns characters, images, transforms, screens, defaults, and defines. Useful for understanding project structure without reading every file.
Args: project_path: Absolute path to the Ren'Py project root directory.
Returns: dict with {characters, images, transforms, screens, defaults, defines}.
Inputs: project_path (required).
tool_list_doc_pagesA
List all available documentation pages in the local docs index.
Returns a list of doc page names and their sizes. Use this to see what documentation is available before searching.
Returns: dict with {ok, pages: [{name, size}], total_pages, total_size}.
Inputs: no named parameters.
tool_list_fixersA
List all available auto-fixers and their descriptions.
Returns a dict mapping fixer names to {description, modifies} info. Use this to see what auto_fix can do before running it.
Inputs: no named parameters.
tool_list_labelsA
List all labels in a Ren'Py project.
Scans all .rpy files under project_path/game/ and returns label names, their source files, and line numbers.
Args: project_path: Absolute path to the Ren'Py project root directory. rich: If True, also parse each label's params, jumps, calls, and return-value status (slower, reads every label block).
Inputs: project_path (required), rich. Returns: result
tool_list_translationsA
List all translation languages in a Ren'Py project.
Scans game/tl/ for language folders and reports, for each language: file count, dialogue block-translation count, string-translation entry count, and which GUI files (common/screens/options) are present. Also reports the project's source language (config.language).
Use this first to see what translations exist before checking them.
Args: project_path: Absolute path to the Ren'Py project root directory.
Returns: dict with {ok, source_language, tl_dir, languages: [{code, files, dialogue_blocks, string_entries, has_common, has_screens, has_options}]}.
Inputs: project_path (required).
tool_manage_savesA
List, clear, or clear-stale Ren'Py save files.
Ren'Py stores saves under game/saves/. Stale saves (_reload-, _tracesave-) can retain old call stacks that cause 'Could not find return label' errors after script refactors.
Args: project_path: Absolute path to the Ren'Py project root directory. action: One of: - "list": list all save files with size + mtime - "clear": delete ALL save files (game restarts from 'start') - "clear_stale": delete only _reload-* and _tracesave-* files
Returns: dict with {ok, action, saves|deleted, message}.
Inputs: project_path (required), action.
tool_read_scriptA
Read the script content of a specific label.
Returns the complete Ren'Py script block under the given label, including all dialogue, menus, and nested logic.
Args: project_path: Absolute path to the Ren'Py project root directory. label_name: The label name to read (e.g. "start", "chapter_01").
Inputs: label_name (required), project_path (required). Returns: result
tool_run_renpyA
Run an arbitrary Ren'Py CLI subcommand via the SDK's bundled Python.
Generic escape hatch for Ren'Py CLI subcommands without a dedicated wrapper.
Useful for translate (generate/refresh translation files), rtc,
add, or for running compile/lint with a custom timeout when the
dedicated tools time out.
Examples:
command="translate", args=["english"] -> generate/refresh English translation files (creates block-translation skeletons).
command="compile" -> same as tool_compile_project.
command="lint" -> same as tool_lint_project.
Args: project_path: Absolute path to the Ren'Py project root directory. command: Ren'Py CLI subcommand (e.g. "compile", "lint", "translate"). args: Extra arguments after the command (e.g. ["english"] for translate). timeout: Override default timeout (seconds). Default via RENPY_MCP_TIMEOUT env var or 180.
Returns: dict with {ok, returncode, raw_output, errors}.
Inputs: command (required), project_path (required), args, timeout.
tool_search_docsA
Search the bundled Ren'Py official documentation (Chinese, from doc.renpy.cn).
Searches through the local copy of the Ren'Py documentation and returns the most relevant sections. Works offline.
Use this BEFORE writing Ren'Py code if you're unsure about syntax, function names, or best practices. For example:
search_docs("Movie") to learn how to play videos
search_docs("screen") to understand screen language
search_docs("transform") to learn about ATL transforms
search_docs("call from") to understand call/from semantics
search_docs("åæ¡£") to find save/load documentation
search_docs("label return") to learn about label return mechanics
Args: query: Search query (supports both English and Chinese). max_results: Maximum number of results to return (default 5).
Returns: dict with {ok, query, results: [{file, title, snippet, score}], result_count}.
Inputs: query (required), max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogâŠ
TDQS
Scored across 19 tools
Most tools have clearly distinct purposes, but there is intentional overlap: run_renpy can duplicate compile/lint, check_project combines compile+lint, and exec_rpy is a universal write escape hatch. These overlaps are well-documented, so misselection risk is low but not zero.
All 19 tools use the same tool_ prefix followed by snake_case verb_noun or verb_noun_phrase patterns. The convention is predictable throughout with no mixed casing or verb styles.
19 tools is slightly above the typical 3-15 range, but the domain is broad (script editing, compilation, linting, assets, saves, docs, translation). Each tool appears to serve a meaningful purpose, though a few convenience tools could be merged.
The surface covers the core Ren'Py development lifecycle well: reading, writing, compiling, linting, fixing, assets, docs, saves, and translation checks. Minor gaps exist (e.g., asset deletion, direct label renaming/deletion), but exec_rpy and run_renpy provide escape hatches for most missing operations.
Maintenance
Related MCP Connectors
Official Duck Framework MCP server for AI-assisted development and project scaffolding.
MCP server for agentverse documentation, generated by doc2mcp.
Official MCP server for Agentwork â delegate tasks to AI agents with human-in-the-loop
Nifty's MCP server â exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server that automates WebGAL game development tasks such as resource management, script editing, documentation lookup, and AI-powered voice generation using LLMs.1-
- AlicenseAqualityCmaintenanceAn MCP server that empowers AI coding agents to work effectively with Minecraft mod development, providing static analysis of decompiled source code and runtime interaction with a running Minecraft instance.3192 npm18MIT
- AlicenseAqualityDmaintenanceUnified MCP server for Construct 3 providing offline documentation, project read/write, analysis, and scripting support. Enables AI-driven game development and project management through natural language.61MIT
- AlicenseCqualityAmaintenanceAn MCP server for Ren'Py project tooling that enables AI agents to inspect game state, evaluate expressions, read/write variables, and capture screenshots from running Ren'Py games.54359 PyPI12MIT