Renpy 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.

Version Python MCP

🎬 See It In Action

🎥 Demo Video

Watch Claude create a complete visual novel in minutes!

📸 Example Outputs

Generated Backgrounds (16:9)

Character Sprites with Multiple Emotions (2:3)

One character with 5 emotions (neutral, happy, sad, surprised, angry) - all generated in a single API call!

Final Playable Games

Fully playable web games with branching dialogue and player choices

✨ 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! 🎮✨