RenForge MCP
RenForge MCP server enables AI agents and humans to inspect, run, edit, test, and package Ren'Py visual-novel projects through MCP tools, a CLI, and a web dashboard.
Inspect projects: summarize structure, scan scripts/labels/assets, find references, parse lint.
Run/control games: launch with Live Editor, poll status, jump/new game/stop, advance dialogue, list/select choices, send input, runtime controls, saves.
Edit live: select/inspect controls, preview layout, save source-safe changes; locked targets inspectable.
Perceive/measure scenes: structured scene tree, UI elements, hit tests, bounds, alignment/spacing/overlap/contrast measurements.
Capture/compare visuals: screenshots with guides/crop/zoom, diff frames, template matching, translation estimation, local image inspection.
Manipulate runtime state: get/set vars, eval expressions, poll events, errors, wait conditions, inspect screens, game state.
Automate: multi-step scenarios, autopilot branch coverage, click/hover/position elements.
Assets/translations: audit orphans/missing, list languages, translation stats, generate translations, export dialogue.
Build/docs: web/desktop builds, search/read/list Ren'Py docs.
Interfaces: MCP server, CLI (inspect/serve/ui), web dashboard.
Provides tools for inspecting and interacting with running Ren'Py projects, including reading/writing variables, evaluating expressions, and capturing screenshots.
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., "@RenForge MCP take a screenshot of the current scene"
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.
RenForge
RenForge is an MCP (Model Context Protocol) server, CLI, and web dashboard for working with Ren'Py visual-novel projects.
It lets an AI agent — or a human via the dashboard — inspect a project, launch
a game with the Live Editor enabled by default, select and inspect on-screen
controls, preview layout changes before writing guarded .rpy source, drive
runtime state, capture screenshots, generate translations, find orphaned
assets, run builds, and search Ren'Py's docs.
Status: alpha, actively developed. The core surfaces (MCP tools, in-game bridge, Live Editor, CLI, dashboard) are functional; APIs may still change.
Quick start — dashboard
Requires Python 3.11+ and uv — nothing else. You don't even need Ren'Py installed: RenForge reuses an SDK it finds on your machine, or downloads one automatically on first launch.
uvx --from "renforge[ui]@latest" renforge uiThen choose your game in the dashboard's project picker — no path to type. (Or
skip the picker with --project /path/to/your/game.) Launch the game and click
the floating RF control to open the Live Editor.
Related MCP server: onyx MCP
Live Editor
The Live Editor is the headline 0.7 feature: edit eligible on-screen controls inside the running game, preview layout changes at runtime, and Save only when a target is source-safe. Locked or unsupported targets stay inspectable with a clear reason — they are not silently forced.
Audience | Start here |
Human | Dashboard or game window → launch → click RF → select from canvas or scene tree → inspect / move where editable → Save → stop cleanly. |
AI agent |
|
Full human and agent workflows, source-safety rules, and screenshots: docs/LIVE_EDITOR.md.
Install
uvx needs no install at all. For a persistent renforge command on your
PATH, use pipx:
# Full install — MCP + CLI + web dashboard
pipx install "renforge[ui]"
renforge ui
# Slim install — MCP server + CLI only (no dashboard deps)
pipx install renforge
renforge serve[ui] pulls in the optional dashboard stack (Starlette, uvicorn, watchfiles).
Skip it if you only need the MCP server or CLI.
On managed systems (Debian/Ubuntu), plain pip install is blocked by
PEP 668 — use uvx or pipx instead.
Update
Installed with | How to update |
| Nothing to do — |
pipx (full or slim) |
|
pip / venv |
|
What's new: CHANGELOG.md · GitHub releases.
Set up the MCP server (AI agents)
The server command is the same for every client:
uvx renforge@latest serveEvery RenForge tool takes a project_path argument, so the agent passes your
game's path on each call — copy the configs below as-is, no path substitution.
Claude Code
claude mcp add renforge -- uvx renforge@latest serveCodex CLI
codex mcp add renforge -- uvx renforge@latest serveClaude Desktop, Cursor, Windsurf, Cline, Gemini CLI — same mcpServers
JSON shape in each client's config file:
{
"mcpServers": {
"renforge": {
"command": "uvx",
"args": ["renforge@latest", "serve"]
}
}
}Client | Config file |
Claude Desktop |
|
Cursor |
|
Windsurf |
|
Cline |
|
Gemini CLI |
|
VS Code (Copilot), Zed, Windows PATH issues, and the pipx variant are covered in the MCP guide.
Verify it works — ask the agent:
Inspect my Ren'Py project at /path/to/game
The agent should call renforge_inspect_project with that path and return a
JSON summary of the project (labels, scripts, assets, and related metadata).
What it does
Live Editor (default on launch) — in-game selection, inspection, and source-safe preview/Save for editable controls; locked targets stay inspectable. Guide: docs/LIVE_EDITOR.md.
Project inspection — summarize structure, scan scripts/labels/assets, parse lint output.
Live game control — launch a project with an injected in-game bridge and Live Editor, then advance dialogue, list/select choices, evaluate expressions, get/set store variables, send focused text/key/scroll input, poll pushed events, and capture frames the model can literally see.
Scene perception (pixel-perfect, no vision needed) — read the whole frame as structured logical-coordinate nodes (
renforge_scene_tree): every sprite, control, and text block with bounds, z-order, colour, and style, plus an ASCII wireframe and structural scene diffs. Thenrenforge_measurereports alignment, spacing, overlap, fit, and WCAG contrast as numbers an agent can act on.Autopilot — auto-play choices backed by Ren'Py menu
itemsacross fresh replays, including custom-named and one-item menus, while reporting label coverage and crashes. Customcall_screeninteractions that do not expose Ren'Py menuitemsare not currently explored automatically.Assets & translations — find orphaned/missing image+audio assets, list languages, compute translation stats, generate/update
game/tl/<lang>/files, export dialogue as text.Builds — package desktop distributions and web builds.
Docs — search and read Ren'Py's offline documentation.
Web dashboard — live story map, activity log, autopilot coverage, lint view, and game-state controls (default
127.0.0.1:8765).
CLI
renforge --version
renforge inspect <project> # lightweight project summary (JSON)
renforge serve [--project .] # start the MCP server (stdio transport)
renforge ui [--project <project>] [--port 8765] # start the web dashboardDocumentation
Live Editor — human and agent workflows, editable vs locked targets, source-safety, public screenshots.
MCP guide — full tool catalogue, agent workflows (Live Editor, hot reload, saves, pixel-perfect placement, scene perception).
Runtime policy — operation-level risk enforcement vs MCP
ToolAnnotations, authorization, and the compatibility plan.Architecture — code layout, live-control flow, Ren'Py SDK resolution, packaging.
Contributing — dev setup, frontend build, PRs.
Cloud / CI environment — Cursor Cloud Agents, Xvfb, Ren'Py SDK bootstrap, and env smoke.
Changelog — release history.
examples/demo_game/— small sample Ren'Py project to try everything on.
License
MIT
Contributors
Special thanks to the people who have contributed to RenForge:
@AxelBeary — complete Simplified Chinese dashboard translation and related internationalization fixes.
Available Tools
54 toolsrenforge_advanceRenforge AdvanceC
Advance the current dialogue.
Inputs: project_path (required). Returns: object
renforge_assetsRenforge AssetsC
Find orphaned and missing image/audio assets in the project.
Inputs: project_path (required). Returns: object
renforge_autopilotRenforge AutopilotC
Auto-play the game across all branches; report label coverage and crashes.
Inputs: project_path (required), max_runs, max_steps. Returns: object
renforge_capture_screenshotRenforge Capture ScreenshotC
Persist a screenshot under the project's controlled capture directory.
Inputs: project_path (required), grid, name, scale, +9 more. Returns: object
renforge_click_atRenforge Click AtC
Click screen coordinates with optional frame/state safety guards.
Inputs: x (required), y (required), project_path (required), expected_state, +2 more. Returns: object
renforge_click_elementRenforge Click ElementB
Click a visible control by text/id, guarded against a stale frame.
Returns received_by when another control owns the hit point. With wait_for_effect=true, wait for a correlated business event such as quick_save.completed when the clicked action is recognizable.
Inputs: project_path (required), text, exact, screen, +5 more. Returns: object
renforge_contextRenforge ContextC
Discover the active Ren'Py project (dashboard, serve default, or cwd).
Inputs: no named parameters. Returns: object
renforge_controlRenforge ControlB
Run a runtime action: advance, rollback, toggle_skip, toggle_auto, toggle_afm, game_menu, hide_windows, quick_save, quick_load, reload_script, restart_interaction, or quit.
Emits correlated business events (quick_save.completed, skip.stopped, …). Set wait_for_effect=true to block until the matching event appears.
Inputs: action (required), project_path (required), effect_timeout, interaction_id, +1 more. Returns: object
renforge_diff_screenshotsRenforge Diff ScreenshotsA
Diff two frames and return the bounding box of what changed.
before_path is a saved PNG. after_path is another saved PNG, or
empty to diff against the current live frame. Use it to measure how far
an element moved or to confirm a tweak left everything else untouched.
Inputs: before_path (required), project_path (required), threshold, after_path. Returns: object
renforge_distributeRenforge DistributeC
Build desktop distributions (e.g. package='pc', 'mac', 'linux').
Inputs: project_path (required), package, destination. Returns: object
renforge_estimate_translationRenforge Estimate TranslationC
Estimate stable visual translation between two saved frames.
Inputs: after_path (required), before_path (required), region_x, region_y, +4 more. Returns: object
renforge_evalRenforge EvalC
Evaluate a Python expression in the running game's store namespace.
Inputs: expr (required), project_path (required). Returns: object
renforge_export_dialogueRenforge Export DialogueC
Export the game's dialogue as plain text.
Inputs: project_path (required), language. Returns: object
renforge_find_image_on_screenRenforge Find Image On ScreenC
Find a template image in the current frame and return its bounds.
Inputs: project_path (required), template_path (required), region_x, region_y, +4 more. Returns: object
renforge_find_referencesRenforge Find ReferencesC
Find exact Ren'Py definitions/usages, including text interpolations.
Inputs: symbol (required), project_path (required), limit, offset, +1 more. Returns: object
renforge_game_stateRenforge Game StateC
Return complete live state; optionally include compact metrics or audio.
Inputs: project_path (required), include. Returns: object
renforge_game_state_compactRenforge Game State CompactB
Return bounded live state, optionally with selected variables.
Defaults to state_profile='interaction' so the full store is never returned in the payload unless state_profile='full' is requested.
Inputs: project_path (required), max_depth, max_items, state_profile, +3 more. Returns: object
renforge_generate_translationsRenforge Generate TranslationsC
Generate/update translation files for a language (writes game/tl//).
Inputs: language (required), project_path (required). Returns: object
renforge_get_displayable_boundsRenforge Get Displayable BoundsC
Report where a shown image tag was rendered, in logical coordinates.
Inputs: tag (required), project_path (required), layer. Returns: object
renforge_get_docRenforge Get DocB
Read a Ren'Py documentation page as plain text (e.g. topic='cli').
Inputs: topic (required). Returns: object
renforge_get_errorsRenforge Get ErrorsC
Return recent bridge exceptions or bounded crash-file diagnostics.
Inputs: project_path (required), since. Returns: object
renforge_get_ui_element_boundsRenforge Get Ui Element BoundsC
Report focus bounds and rendered painted bounds for a UI element.
Inputs: project_path (required), text, exact, screen, +2 more. Returns: object
renforge_get_varRenforge Get VarC
Read a variable from the running game's store.
Inputs: name (required), project_path (required). Returns: object
renforge_hit_testRenforge Hit TestB
Inspect the interactive focus stack at a coordinate.
Returns topmost and underneath focusable controls so agents can detect transparent overlays that intercept clicks.
Inputs: x (required), y (required), project_path (required), coordinate_space. Returns: object
renforge_hover_elementRenforge Hover ElementC
Move the pointer over a visible control without clicking it.
Inputs: project_path (required), text, exact, screen, +2 more. Returns: object
renforge_infoRenforge InfoA
Call first: report RenForge version and the active project.
active_project falls back from the dashboard selection to the serve default, then to a Ren'Py project detected from the current directory (project_source says which one matched). A null active_project only means auto-discovery found nothing — every tool accepts project_path directly, so ask the user for the game's path and keep going.
Inputs: no named parameters. Returns: object
renforge_inspect_imageRenforge Inspect ImageC
Open a local image and return an optional cropped/zoomed PNG for inspection.
Inputs: image_path (required), scale, crop_x, crop_y, +2 more.
renforge_inspect_projectRenforge Inspect ProjectD
Inputs: project_path (required). Returns: object
renforge_inspect_screenRenforge Inspect ScreenC
Inspect an active screen's layer, JSON-safe scope, and arguments.
Inputs: name (required), project_path (required). Returns: object
renforge_jumpRenforge JumpC
Restart at a label or file:line; poll launch status when still starting.
Inputs: target (required), project_path (required), version. Returns: object
renforge_languagesRenforge LanguagesC
List translation languages present under game/tl/.
Inputs: project_path (required). Returns: object
renforge_launchRenforge LaunchA
Launch or reuse a game with the Live Editor enabled by default.
Pass editor=False to launch intentionally without the visual editor.
After launch, poll renforge_launch_status until ready, then observe
with a fresh renforge_screenshot or renforge_scene_tree before
any click. Use renforge_click_at or renforge_click_element with
a current frame_id guard; verify the result, then renforge_stop.
See docs/LIVE_EDITOR.md. Optional warp is a Ren'Py file:line target.
The call waits at most 20 seconds for readiness, then returns
status="starting" while startup continues in the background. Poll
renforge_launch_status until it reports ready or failed.
display/audio default to auto; savedir='temporary' isolates saves.
timeout controls the background startup deadline, not the MCP call.
Inputs: project_path (required), warp, audio, editor, +6 more. Returns: object
renforge_launch_statusRenforge Launch StatusB
Return starting, ready, failed, or idle for a background launch.
Inputs: project_path (required). Returns: object
renforge_list_choicesRenforge List ChoicesC
List the on-screen menu choices (text + index).
Inputs: project_path (required). Returns: object
renforge_list_docsRenforge List DocsB
List available Ren'Py documentation topics.
Inputs: no named parameters. Returns: object
renforge_list_ui_elementsRenforge List Ui ElementsC
List visible focusable Ren'Py controls with bounds and frame guard.
Inputs: project_path (required), text, screen, element_type. Returns: object
renforge_measureRenforge MeasureA
Measure pixel relationships between scene nodes, without eyes.
action is one of align, gap, distribute, center, overlap,
fit, contrast. Each target (and within) is a renforge_scene_tree
node id (string, resolved live) or a literal bounds object
{x,y,width,height}. Returns actionable deltas in logical pixels; when
tolerance is given, adds a pass verdict. contrast samples the live
frame and reports a WCAG ratio (one target = its internal fg/bg, two
targets = between the two elements).
Inputs: action (required), targets (required), project_path (required), within, +1 more. Returns: object
renforge_new_gameRenforge New GameC
Start at the start label; poll launch status when still starting.
Inputs: project_path (required), version. Returns: object
renforge_parse_lintRenforge Parse LintD
Inputs: text (required). Returns: object
renforge_poll_eventsRenforge Poll EventsB
Return pushed events (dialogue, labels, exceptions) newer than since.
Inputs: project_path (required), since. Returns: object
renforge_position_elementRenforge Position ElementA
Reposition a shown image tag live and return its new logical bounds.
Provide at least one placement field. The tag keeps its current
attributes. Positions follow Ren'Py's rule: an integer is absolute
pixels (xpos=600 is 600px), a float is a fraction of the screen
(xpos=0.5 is the centre). Use this to converge on coordinates
interactively, then write the final values into the .rpy script.
Inputs: tag (required), project_path (required), xpos, ypos, +9 more. Returns: object
renforge_run_scenarioRenforge Run ScenarioB
Run a multi-step live scenario (click/wait/assert/...) in one call.
On failure, captures a screenshot and compact diagnostics automatically. Supported step actions: set, eval, click, click_at, advance, scroll, wait, assert, select_choice, capture, save, load, control, send_input.
Inputs: steps (required), project_path (required), name, timeout, +3 more. Returns: object
renforge_savesRenforge SavesC
Save, load, or list named save slots without screenshot payloads.
Inputs: action (required), project_path (required), slot, regexp, +1 more. Returns: object
renforge_scan_projectRenforge Scan ProjectC
Scan scripts; defaults to summary-only, with opt-in sections and pagination.
Inputs: project_path (required), limit, offset, symbol, +2 more. Returns: object
renforge_scene_treeRenforge Scene TreeA
Perceive the whole scene as structured data (logical coordinates).
Unlike renforge_list_ui_elements (focusables only), this reports every
layer displayable, focusable control, and text block with id, type,
bounds, center, zorder and screen. Every reply carries an
omitted completeness hint. detail is semantic (default), layout
or raw; layers/types/screen/ids scope the result.
include=["color","style","overflow"] opts into composited colour,
declared style, and best-effort text overflow. format="wireframe" adds
an ASCII map. save_as persists a snapshot under .renforge/scenes/;
diff_against diffs the live scene against a saved snapshot.
Inputs: project_path (required), ids, types, detail, +9 more. Returns: object
renforge_screenshotRenforge ScreenshotB
Capture a game frame, optionally resizing, cropping, and zooming it.
Measurement guides help pixel-perfect placement: grid draws lines
every N pixels, rulers labels those steps along the edges, and
crosshair_x/crosshair_y mark a point. Capture at the game's
logical resolution (width/height) so the labels read as logical
coordinates. Passing only one of width/height keeps the game's
aspect ratio.
Inputs: project_path (required), grid, scale, width, +8 more.
renforge_search_docsRenforge Search DocsC
Search Ren'Py's offline documentation for a keyword.
Inputs: query (required). Returns: object
renforge_select_choiceRenforge Select ChoiceB
Select a menu choice by visible text (preferred) or by index.
Inputs: project_path (required), text, index. Returns: object
renforge_send_inputRenforge Send InputB
Send exactly one input mode: text, named key, or scroll object.
text posts character-by-character TEXTINPUT events to a focused
Ren'Py Input; submit optionally presses Enter after the text.
key accepts readable names such as enter, esc, arrows, pageup,
pagedown, backspace, delete, home, end, space, tab, and function keys.
scroll is {"x": ..., "y": ..., "direction": "up"|"down"}
in logical game coordinates, with optional integer amount.
Exactly one of text, key, and scroll must be supplied.
Inputs: project_path (required), key, text, scroll, +1 more. Returns: object
renforge_set_varRenforge Set VarC
Set a variable in the running game's store namespace.
Inputs: name (required), value (required), project_path (required). Returns: object
renforge_stopRenforge StopC
Stop a running game or cancel its in-progress launch, then clean up.
Inputs: project_path (required). Returns: object
renforge_translation_statsRenforge Translation StatsC
Report missing dialogue/string translation counts for a language.
Inputs: language (required), project_path (required). Returns: object
renforge_wait_untilRenforge Wait UntilB
Wait for exactly one label, screen, or expression condition.
Returns a compact state by default (state_profile='interaction'). Pass include for extra fields/variables; use state_profile='full' only when the complete store is required.
Inputs: project_path (required), expr, label, screen, +7 more. Returns: object
renforge_web_buildRenforge Web BuildC
Package the project as a browser-playable build (needs the web DLC).
Inputs: project_path (required), destination. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 54 tools
The set has multiple overlapping tools: renforge_info vs renforge_context both discover the active project; renforge_screenshot vs renforge_capture_screenshot blur capture/persist; renforge_advance duplicates part of renforge_control; renforge_game_state and renforge_game_state_compact create state-reading ambiguity. Two tools (renforge_inspect_project, renforge_parse_lint) have no descriptions at all, worsening boundaries.
All 54 tools use a uniform `renforge_` snake_case prefix with no camelCase or mixed conventions. Although some names are noun-based (renforge_info) and some verb-based (renforge_click_at), the pattern is predictable and consistent throughout.
54 tools far exceeds the 50+ threshold for extreme mismatch; even for a broad Ren'Py automation domain, the surface is bloated. Many operations (advance, bounds, state, screenshots) are duplicated across separate tools, indicating poor scoping.
The set covers project discovery, scanning, docs, live launch/control, UI automation, screenshots, scene perception, variables, events, saves, translations, assets, builds, and autopilot. No obvious workflow dead ends appear for Ren'Py development and testing, aside from direct script editing which may be outside this server's control plane.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
MCP server for building and testing AI agents with multi-model experimentation and insights.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
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-
- AlicenseNot gradedqualityDmaintenanceLocal MCP server that gives AI agents 44 engine tools to build, run, and debug real 2D and 3D games through conversation.MIT
- 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.3159 npm18MIT
- FlicenseAqualityDmaintenanceAn MCP server that provides a visual novel world engine, enabling AI clients to drive interactive galgame experiences with narrative consistency.31-