Creatomate Server

This is a Model Context Protocol (MCP) server that interfaces with the Creatomate API. It turns LLMs (like Claude, ChatGPT) into autonomous Senior Motion Designers capable of generating industry-standard social media videos, ads, and shorts programmatically.

🚀 The Crux

This server goes beyond simple video rendering. It is architected to produce viral-style content (Reels/Shorts/TikTok) by enforcing:

1. Kinetic Typography: Word-by-word "karaoke" animations.
2. Auto-Captions: Automatic synchronization between AI Voiceovers (TTS) and Text.
3. Social Safe Zones: Smart defaults for 9:16 aspect ratios and readable text overlays.
4. Hallucination Prevention: Exposes valid animation dictionaries to the LLM via Resources.

---

🏗 Server Structure

The server is built on the @modelcontextprotocol/sdk and exposes the following three primitives:

1. Resources (Data Context)

creatomate://catalog/animations

• Purpose: Provides the LLM with a strict JSON catalog of valid animation types (text-slide, scale, wipe) and easing functions (elastic-out, bounce-out).
• Why: Prevents the LLM from inventing animations that don't exist in the Creatomate engine.

2. Prompts (Agent Personas)

design-social-ad

• Arguments: topic, platform (Instagram, TikTok, YouTube).
• Behavior: Sets the LLM's system instruction to "Senior Motion Designer."
• Logic: Enforces a checklist before tool use:
  • Must use 9:16 aspect ratio.
  • Must use short scenes (2-4s).
  • Must link Audio tracks to Text layers for auto-captions.

3. Tools (Action Capabilities)

render_video

• Capabilities: The core engine that constructs the render script.
• Advanced Features:
  • TTS Integration: Converts audio elements with text sources into speech (via Google/ElevenLabs).
  • Auto-Captions: Uses the transcript_source property to link a Text element to an Audio element.
  • Styling: Supports "Sticker" styles (background boxes with padding/radius) for high readability.

---

💻 Installation & Setup

Prerequisites

• Node.js (v18+)
• A Creatomate API Key

1. Environment

Create a .env file in the root directory:

CREATOMATE_API_KEY=your_api_key_here

2. Install Dependencies

npm install

3. Build

npm run build

---

🔌 Transports & Usage

This server supports both Stdio (for local desktop apps like Claude Desktop) and SSE (Server-Sent Events for remote web integration).

Option A: Stdio (Local / Claude Desktop)

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "creatomate": {
      "command": "node",
      "args": ["dist/index-stdio.js"],
      "env": {
        "CREATOMATE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option B: SSE (Web / Remote)

If running as a standalone HTTP server (e.g., for a web-based chat interface):

# Assumes your code exports an SSE handler or runs a server on a port
node dist/index-sse.js --transport sse --port 3000

Note: Ensure your code implements the SSEServerTransport logic if you intend to run this mode.

---

🧠 LLM Workflow Example

Here is how the LLM interacts with the server internally:

1. User: "Make a hype video for my new energy drink."
2. LLM (Prompt design-social-ad): "I need to make a 9:16 video. I will use the 'text-slide' animation."
3. LLM (Tool render_video): Generates this payload:

{
  "width": 1080,
  "height": 1920,
  "elements": [
    {
      "type": "video",
      "track": 1,
      "source": "https://stock-footage..."
    },
    {
      "type": "audio",
      "track": 2,
      "name": "voiceover_main",
      "source": "Wake up. Focus. Dominate.",
      "provider": "google"
    },
    {
      "type": "text",
      "track": 3,
      "transcript_source": "voiceover_main",
      "fillColor": "#FFFF00",
      "enter": { "type": "text-slide", "scope": "split-clip", "split": "word" }
    }
  ]
}

4. Server: Renders the video via Creatomate and returns the MP4 URL.

---

🛠 Troubleshooting

• Error: API Key Missing: Ensure .env is loaded. If using Stdio via Claude Desktop, the env var must be in the claude_desktop_config.json, not just the local .env.
• Video Render Failed: Check the render_video tool output. If the stock asset URL is broken, Creatomate will fail.
• Captions not syncing: Ensure the name property of the Audio element exactly matches the transcript_source of the Text element.