Ren'Py Skill for Codex

Create visual novels directly in your workspace: write the story, generate character art, build for the web, and playtest in the browser.

Use the Ren'Py skill for new games. It is the recommended workflow in this repository. The Python MCP server and Ren'Py Studio MCP App remain available for existing integrations; their setup is in the legacy server guide and Studio documentation.

Install the skill

Install with the Skills CLI:

npx skills add banjtheman/renpy_mcp_server --skill renpy --agent codex --global

Omit --global for a project-local installation. Use npx skills add banjtheman/renpy_mcp_server --list to inspect the available skills before installing. Node.js/npm is needed for this installer; the Ren'Py helper itself uses Python.

Or ask Codex to use its bundled installer:

Use $skill-installer to install the Ren'Py skill from
https://github.com/banjtheman/renpy_mcp_server/tree/main/skills/renpy

For a manual installation, copy the entire skills/renpy folder into your Codex skills directory. The bundled skill installer uses $CODEX_HOME/skills, which defaults to ~/.codex/skills. Keep its scripts, assets, and references together. If a renpy skill already exists there, update that installation rather than nesting another folder inside it. The skill works independently of this repository once copied.

Start a fresh Codex task in the workspace where you want the game and ask:

Use $renpy to make a short mystery visual novel with two distinct endings.
Generate backgrounds and consistent character expressions with native ImageGen.
Build it for the web, open the preview, and playtest both endings in the browser.

For an existing game, include its project path and the change you want. See adopting the skill in an existing project.

Related MCP server: RPG Maker MV MCP Server

What the workflow includes

• Direct authoring: ordinary .rpy scripts, game assets, and concise story notes in your workspace.

• Native ImageGen: backgrounds and character variants based on inspected references, with checks for lighting, pose, framing, and real transparency. The native host manages its image model.

• Reproducible web builds: a pinned Ren'Py 8.5.3 SDK and matching web runtime, verified downloads, engine lint, and upstream web_build packaging.

• Local browser preview: an owned loopback server, build logs, and explicit rebuild/reload behavior.

• Browser playtesting: screenshots and story state, with WebMCP actions for reading state, starting, advancing dialogue, and choosing an option. An accessible controls panel is available when native WebMCP is unsupported.

Game creation does not require configuring an MCP server, running the repository's setup.sh, or installing its Gemini dependencies. Those belong to the legacy integration. The skill's helper uses Python's standard library and the SDK's bundled runtime.

Requirements and tools

Use Python 3.11.8+, network access for the initial SDK download, and a browser for preview. Generated art additionally needs native ImageGen in the host. WebMCP needs a compatible browser; ordinary gameplay and the fallback controls work without it. The SDK pin and browser workflow were verified on macOS; consult the validation record for the checks performed.

Codex normally invokes the helper for you. You can also use it directly from this checkout with a Python 3.11.8+ interpreter available as python:

python skills/renpy/scripts/renpy.py setup
python skills/renpy/scripts/renpy.py doctor
python skills/renpy/scripts/renpy.py init /absolute/path/my-game --title "My Game"
python skills/renpy/scripts/renpy.py lint /absolute/path/my-game
python skills/renpy/scripts/renpy.py build-web /absolute/path/my-game
python skills/renpy/scripts/renpy.py serve /absolute/path/my-game

serve returns the preview URL. After edits, rebuild with build-web /absolute/path/my-game --force and reload the browser. Use status /absolute/path/my-game or stop /absolute/path/my-game with the same helper to inspect or stop the preview.

Web builds go into a sibling my-game-web directory. The separate test command runs authored Ren'Py testcases and opens a native game window; browser playtests are the default for web previews.

Documentation

• Skill instructions

• Story, art, and expression consistency

• SDK, builds, and preview

• WebMCP and browser controls

• Moving an existing game to the skill

• Validation record

• Contributing and running tests

Watch Codex play through WebMCP

The web build exposes four semantic tools directly to a compatible browser. Codex can discover and invoke them through its browser's native WebMCP capability:

Actions use the current state revision so an agent cannot accidentally act on an outdated menu. The bridge runs inside the web game and preserves normal Ren'Py choice behavior. This is browser-native WebMCP; it does not require launching the repository's MCP server.

Playtests combine these state-driven actions with screenshots of the actual game. A JavaScript fallback or a successful build alone does not demonstrate native WebMCP. The validation record identifies the native calls and routes already exercised.

The timelapse recording plan follows a real Codex session from the initial prompt through story, art, web build, and direct WebMCP gameplay. The new recording will be added here once captured; the older MCP demos are preserved in the legacy guide.

Existing MCP integrations

The repository name remains renpy_mcp_server, so existing clone URLs continue to work. The server code, entry point, and Studio App remain in place. Use the legacy MCP server guide, MCP integration examples, or Studio App README when maintaining those integrations.

License

MIT.