sanzaru

sanzaru

A stateless, lightweight MCP server that wraps OpenAI's Sora Video API, Whisper, GPT-4o Audio, and TTS APIs via the OpenAI Python SDK.

Features

Video Generation (Sora)

• Create videos with sora-2 or sora-2-pro models
• Use reference images to guide generation
• Remix and refine existing videos
• Download variants (video, thumbnail, spritesheet)

Image Generation

• Generate images with gpt-image-1.5 (recommended) or GPT-5
• Edit and compose images with up to 16 inputs
• Iterative refinement via Responses API
• Automatic resizing for Sora compatibility

Audio Processing

• Transcription: Whisper and GPT-4o models
• Audio Chat: Interactive analysis with GPT-4o
• Text-to-Speech: Multi-voice TTS generation
• Processing: Format conversion, compression, file management

Podcast Generation

• Multi-voice podcasts with up to 4 speakers and 10 TTS voices
• Parallel segment generation with configurable pacing
• MP3/WAV output with loudness normalization

Note: Content guardrails are enforced by OpenAI. This server does not run local moderation.

Requirements

• Python 3.10+
• OPENAI_API_KEY environment variable

Media storage (choose one):

# Recommended: unified path (auto-creates videos/, images/, audio/ subdirs)
SANZARU_MEDIA_PATH="/path/to/media"

# Or individual paths (legacy, still supported)
VIDEO_PATH="/path/to/videos"
IMAGE_PATH="/path/to/images"
AUDIO_PATH="/path/to/audio"

Features are auto-detected based on configured paths. Set only what you need.

Quick Start

1. Clone the repository:

   git clone https://github.com/TJC-LP/sanzaru.git
   cd sanzaru
   

2. Run the setup script:

   ./setup.sh
   

   The script will:

   • Prompt for your OpenAI API key
   • Create directories and .env configuration
   • Install dependencies with uv sync --all-extras --dev

3. Start using:

   claude
   

That's it! Claude Code will automatically connect and you can start generating videos, images, and processing audio.

Installation

Claude Code Plugin (Recommended)

Install as a plugin — auto-configures the MCP server + includes prompting guidance:

/plugin marketplace add TJC-LP/sanzaru

Requires OPENAI_API_KEY and SANZARU_MEDIA_PATH environment variables to be set.

Quick Install

# All features
uv add "sanzaru[all]"

# Specific features
uv add "sanzaru[audio]"  # With audio support
uv add sanzaru           # Base (video + image only)

git clone https://github.com/TJC-LP/sanzaru.git
cd sanzaru
uv sync --all-extras

{
  "mcpServers": {
    "sanzaru": {
      "command": "uvx",
      "args": ["sanzaru[all]"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "SANZARU_MEDIA_PATH": "/absolute/path/to/media"
      }
    }
  }
}

{
  "mcpServers": {
    "sanzaru": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sanzaru", "sanzaru"]
    }
  }
}

# Using uvx (from PyPI)
codex mcp add sanzaru \
  --env OPENAI_API_KEY="sk-..." \
  --env SANZARU_MEDIA_PATH="$HOME/sanzaru-media" \
  -- uvx "sanzaru[all]"

uv venv
uv sync

# Set required environment variables
export OPENAI_API_KEY=sk-...
export SANZARU_MEDIA_PATH=~/sanzaru-media

# Run server (stdio for MCP clients)
uv run sanzaru

# Or HTTP mode (for remote access)
uv run sanzaru --transport http --port 8000

Available Tools