🎮 Ren'Py MCP Server

Build visual novels with AI! An Model Context Protocol server that lets AI assistants create complete Ren'Py visual novel games with images, dialogue, branching stories, and web deployment.

<p align="center"> <img src="media/images/workflow_diagram.png" width="90%" alt="From AI-generated assets to playable game" /> </p>

🎬 See It In Action

🎥 Demo Video

<p align="center"> <img src="media/videos/claude_renpy_mcp.gif" width="80%" alt="Claude creating a visual novel in real-time" /> </p> <p align="center"><em>Watch Claude create a complete visual novel in minutes!</em></p>

📸 Example Outputs

Generated Backgrounds (16:9)

<p align="center"> <img src="media/images/example_background_cafe.png" width="45%" alt="Cozy Cafe Interior" /> <img src="media/images/example_background_tennis.png" width="45%" alt="Tennis Court Scene" /> </p>

Character Sprites with Multiple Emotions (2:3)

<p align="center"> <img src="media/images/example_character_emotions.png" width="80%" alt="Character showing 5 emotions: neutral, happy, sad, surprised, angry" /> </p> <p align="center"><em>One character with 5 emotions (neutral, happy, sad, surprised, angry) - all generated in a single API call!</em></p>

Final Playable Games

<p align="center"> <img src="media/images/game_screenshot_3_dialogue.png" width="45%" alt="Game dialogue scene" /> <img src="media/images/game_screenshot_5_choice_menu.png" width="45%" alt="Interactive choice menu" /> </p> <p align="center"><em>Fully playable web games with branching dialogue and player choices</em></p>

✨ Features

• 🎨 AI Image Generation - Backgrounds (16:9) and characters (2:3) using Gemini 2.5 Flash Image
• 🎭 Emotion System - Generate 5 emotions per character in one API call (neutral, happy, sad, surprised, angry)
• 📝 Script Generation - AI writes complete Ren'Py scripts with dialogue, choices, and branching paths
• 🌐 Web Builds - Automatically compile to playable web games
• 🎬 Live Preview - Local HTTP server to test games instantly
• 🪄 Transparent Sprites - Automatic background removal for character sprites

🚀 Quick Start

Automated Setup

# Clone and setup everything automatically
git clone https://github.com/banjtheman/renpy_mcp_server.git
cd renpy_mcp_server
./setup.sh

# Test your installation
./test_setup.sh

# (Optional) Test image generation directly
uv run python test_nano_banana.py

The setup.sh script will:

• ✅ Install Python dependencies
• ✅ Download and setup Ren'Py SDK (OS-specific)
• ✅ Automatically install web support module
• ✅ Help configure Gemini API key
• ✅ Create MCP configuration files
• ✅ Test everything works

MCP Client Configuration

Add the server to your MCP client configuration (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "renpy_mcp_server": {
      "command": "uv",
      "args": [
        "--directory",
        "/FULL_PATH_TO_RENPY_MCP_SERVER",
        "run",
        "renpy-mcp-server"
      ],
      "env": {
        "GEMINI_API_KEY": "${GEMINI_API_KEY}",
        "RENPY_SDK_PATH": "${RENPY_SDK_PATH}"
      }
    }
  }
}

Replace:

• /FULL_PATH_TO_RENPY_MCP_SERVER - Full path to this repository
• ${GEMINI_API_KEY} - Your Gemini API key
• ${RENPY_SDK_PATH} - Path to Ren'Py SDK (e.g., /path/to/renpy-8.4.1-sdk)

Or use environment variables:

export GEMINI_API_KEY="your-api-key"
export RENPY_SDK_PATH="/path/to/renpy-8.4.1-sdk"

Manual Setup

1. Install Dependencies

   uv sync
   

2. Setup Ren'Py SDK

   • SDK and web module are automatically downloaded during setup
   • No manual launcher interaction needed

3. Get Gemini API Key

   • Visit Google AI Studio
   • Create an API key

4. Configure Environment

   export RENPY_SDK_PATH="/path/to/renpy-sdk"
   export GEMINI_API_KEY="your-api-key"
   

5. Add to MCP Client

   • See "MCP Client Configuration" section above
   • The server will start automatically when your MCP client connects

🎮 Usage

Basic Workflow

1. Create a project

   create_project(name="my_vn")
   

2. Generate assets

   generate_background(project_name="my_vn", description="Cozy café interior, evening time...")
   generate_character(project_name="my_vn", character_name="alice", description="Friendly barista...", generate_emotions=True)
   

3. Write the story

   generate_script(project_name="my_vn", script_name="intro", script_content="label intro:\n    scene bg cafe\n    show alice happy\n    Alice \"Welcome!\"\n    return")
   

4. Inspect and edit (optional)

   list_project_files(project_name="my_vn")  # See all files
   read_project_file(project_name="my_vn", file_path="intro.rpy")  # Read a script
   edit_project_file(project_name="my_vn", file_path="intro.rpy", content="...")  # Update it
   

5. Build and preview

   build_project(project_name="my_vn")
   start_web_preview(project_name="my_vn")
   

📚 Documentation

• Examples - Claude Agent SDK and Strands integration examples

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

---

Happy visual novel creating! 🎮✨