README - creatify-mcp by tsavo

🎬 Creatify MCP Server

The ultimate MCP server for AI video generation - Bringing Creatify AI's powerful video creation capabilities to every AI assistant in the MCP ecosystem.

🌟 Overview

The Creatify MCP Server is a comprehensive Model Context Protocol (MCP) server that exposes the full power of Creatify AI's video generation platform to AI assistants, chatbots, and automation tools. Built on top of the robust @tsavo/creatify-api-ts TypeScript client library, this server transforms complex video creation workflows into simple, natural language interactions.

🎨 Advanced MCP Features:

📝 Prompts - Reusable video creation templates and workflows
📊 Logging - Structured logging with multiple severity levels
🔍 Progress Tracking - Real-time updates during video generation
🤖 AI Self-Help - how_to_use tool for AI assistants to understand parameters
📊 Notifications - Real-time status updates and progress notifications

🎯 What This Enables

Imagine telling Claude Desktop: "Create a 16:9 avatar video of Anna saying 'Welcome to our product demo' and wait for it to complete" - and having it actually happen. That's the power of this MCP server.

🏗️ Built With

Creatify AI API - The world's leading AI video generation platform
@tsavo/creatify-api-ts - Comprehensive TypeScript client library
Model Context Protocol - Standardized AI assistant integration
TypeScript - Full type safety and excellent developer experience

Features

🛠️ MCP Tools (12 powerful actions)

create_avatar_video - Create AI avatar videos with lip-sync
create_url_to_video - Convert websites into professional videos
generate_text_to_speech - Generate natural-sounding speech from text
create_multi_avatar_conversation - Create videos with multiple avatars having conversations
create_custom_template_video - Generate videos using custom templates
create_ai_edited_video - Automatically edit and enhance videos
create_ai_shorts - Create short-form videos (perfect for TikTok, Instagram Reels)
generate_ai_script - Generate AI-powered scripts for videos
create_custom_avatar - Design and create your own custom avatars (DYOA)
manage_music - Upload, manage, and use background music
create_advanced_lipsync - Advanced lip-sync with emotion and gesture control
how_to_use - Get detailed usage information for any tool
get_video_status - Check the status of video generation tasks

📚 MCP Resources (6 data sources)

creatify://avatars - List of available AI avatars
creatify://voices - List of available voices for text-to-speech
creatify://templates - Available custom video templates
creatify://music - Available background music library
creatify://credits - Remaining API credits
creatify://avatar/{avatarId} - Detailed information about specific avatars

🏆 Why Choose Creatify MCP Server?

🚀 Complete API Coverage

✅ 12 MCP Tools covering 100% of Creatify API functionality
✅ 6 MCP Resources for comprehensive data access
✅ 5 Workflow Prompts for common video creation scenarios
✅ Enterprise-grade logging with 8 severity levels

🤖 AI-First Design

✅ Self-documenting with how_to_use tool for AI assistants
✅ Intelligent parameter validation and error handling
✅ Real-time progress updates during video generation
✅ Semantic versioning with automated releases

🎨 Advanced Features

✅ Emotion & gesture control in advanced lip-sync
✅ Custom avatar creation (DYOA - Design Your Own Avatar)
✅ AI-powered script generation for any video type
✅ Short-form video optimization for TikTok/Instagram/YouTube
✅ Background music management and integration

💼 Production Ready

✅ TypeScript for type safety and better IDE support
✅ Comprehensive error handling with detailed context
✅ Professional logging for monitoring and debugging
✅ Automated testing and continuous integration
✅ Semantic versioning for reliable updates

📝 MCP Prompts (5 workflow templates)

create-product-demo - Professional product demonstration workflow
create-social-content - Engaging social media content creation
create-educational-video - Educational and tutorial video workflow
create-marketing-campaign - Marketing campaign video creation
analyze-video-performance - Video performance analysis and optimization

Prerequisites

Node.js 18 or higher
Creatify API credentials (Pro plan or higher)
- Get your API credentials from Creatify account settings

Installation

From npm (recommended)

npm install -g @tsavo/creatify-mcp

From source

git clone https://github.com/TSavo/creatify-mcp.git
cd creatify-mcp
npm install
npm run build
npm link

🎬 Live Demo Examples

Create an AI Avatar Video

User: "Create a professional avatar video with Anna saying 'Welcome to our company!' in 16:9 format"

Claude: I'll create a professional avatar video for you using the Creatify MCP Server.

[Uses create_avatar_video tool with:
- text: "Welcome to our company!"
- avatarId: "anna_costume1_cameraA"
- aspectRatio: "16:9"
- voiceId: "en-US-AriaNeural"]

Your professional avatar video has been created! Anna delivers your message with natural lip-sync and professional presentation.

Generate TikTok-Style Short Video

User: "Make a 30-second TikTok video about coffee brewing tips"

Claude: I'll create an engaging short-form video perfect for TikTok!

[Uses create_ai_shorts tool with:
- prompt: "Quick coffee brewing tips with energetic presentation"
- aspectRatio: "9:16"
- duration: 30
- style: "energetic"]

Your TikTok-ready short video is being generated with optimal 9:16 aspect ratio and engaging content!

Convert Website to Video

User: "Turn my product landing page into a marketing video"

Claude: I'll convert your website into a compelling marketing video.

[Uses create_url_to_video tool with:
- url: "https://yourproduct.com"
- aspectRatio: "16:9"
- style: "marketing"]

Your landing page has been transformed into a professional marketing video showcasing your product!

AI-Powered Script Generation

User: "Generate a script for a 60-second product demo video"

Claude: I'll create a compelling script for your product demo.

[Uses generate_ai_script tool with:
- topic: "Product demonstration video"
- scriptType: "commercial"
- duration: 60
- tone: "professional"]

Your script is ready! It includes engaging hooks, clear value propositions, and a strong call-to-action optimized for 60-second format.

Configuration

Set your Creatify API credentials as environment variables:

export CREATIFY_API_ID="your-api-id"
export CREATIFY_API_KEY="your-api-key"

Or create a .env file:

CREATIFY_API_ID=your-api-id
CREATIFY_API_KEY=your-api-key

Usage

With Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "creatify": {
      "command": "creatify-mcp",
      "env": {
        "CREATIFY_API_ID": "your-api-id",
        "CREATIFY_API_KEY": "your-api-key"
      }
    }
  }
}

🎨 Advanced MCP Features

📝 Using Prompts (Workflow Templates)

AI assistants can now use predefined workflow templates for common video creation scenarios:

Example: Product Demo Workflow

User: "Use the create-product-demo prompt for 'Amazing Widget' with features 'fast, reliable, easy to use' targeting small business owners"

Claude: I'll use the product demo workflow template to create a professional demonstration video.

[Claude automatically follows the complete workflow:
1. Generates an engaging script using generate_ai_script
2. Creates avatar video using create_avatar_video
3. Optimizes for the target audience
4. Includes clear call-to-action]

Available Prompt Templates:

create-product-demo - Professional product demonstrations
create-social-content - TikTok/Instagram/YouTube content
create-educational-video - Tutorials and educational content
create-marketing-campaign - Marketing and promotional videos
analyze-video-performance - Video optimization and analysis

📊 Real-time Logging & Progress

The server provides structured logging with multiple severity levels:

[INFO] Creatify MCP Server initialized
[INFO] Creating avatar video {avatarId: "anna_costume1_cameraA", aspectRatio: "16:9"}
[INFO] Waiting for avatar video completion...
[INFO] Avatar video completed {videoId: "video_abc123"}

Log Levels: debug, info, notice, warning, error, critical, alert, emergency

🤖 AI Self-Help System

AI assistants can now understand tool parameters better using the how_to_use tool:

Claude: Let me check how to use the avatar video tool...

[Calls how_to_use tool with toolName: "create_avatar_video"]

[Gets comprehensive documentation with:
- Required parameters with descriptions
- Optional parameters with usage notes
- Real code examples
- Tips and best practices]

Now I understand exactly how to create your avatar video!

With Custom MCP Client

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "creatify-mcp",
  env: {
    CREATIFY_API_ID: "your-api-id",
    CREATIFY_API_KEY: "your-api-key"
  }
});

const client = new Client({
  name: "my-client",
  version: "1.0.0"
});

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log("Available tools:", tools.tools.map(t => t.name));

// Create an avatar video
const result = await client.callTool({
  name: "create_avatar_video",
  arguments: {
    text: "Hello, world! This is an AI-generated video.",
    avatarId: "anna_costume1_cameraA",
    aspectRatio: "16:9",
    waitForCompletion: true
  }
});

Standalone Server

# Set environment variables
export CREATIFY_API_ID="your-api-id"
export CREATIFY_API_KEY="your-api-key"

# Run the server
creatify-mcp

Example Prompts for AI Assistants

Once configured with Claude Desktop or another MCP client, you can use natural language prompts like:

"Create a 16:9 avatar video of Anna saying 'Welcome to our product demo' and wait for it to complete"
"Convert the website https://example.com into a promotional video"
"Generate text-to-speech audio for 'Hello world' using a professional voice"
"Show me all available avatars and their details"
"Check my remaining Creatify credits"
"Create a conversation between two avatars discussing our new product"

API Reference

Tools

`create_avatar_video`

Create an AI avatar video with lip-synced speech.

Parameters:

text (string, required) - Text to be spoken
avatarId (string, required) - Avatar ID to use
aspectRatio ("16:9" | "9:16" | "1:1", required) - Video aspect ratio
voiceId (string, optional) - Voice ID for the avatar
waitForCompletion (boolean, optional) - Wait for video completion

`create_url_to_video`

Convert a website URL into a professional video.

Parameters:

url (string, required) - URL to convert
visualStyle (string, optional) - Visual style template
scriptStyle (string, optional) - Script writing style
aspectRatio ("16:9" | "9:16" | "1:1", optional) - Video aspect ratio
waitForCompletion (boolean, optional) - Wait for video completion

`generate_text_to_speech`

Generate natural-sounding speech from text.

Parameters:

text (string, required) - Text to convert to speech
voiceId (string, required) - Voice ID to use
waitForCompletion (boolean, optional) - Wait for audio completion

`get_video_status`

Check the status of a video generation task.

Parameters:

videoId (string, required) - Video/task ID to check
videoType (string, required) - Type of task ("lipsync", "url-to-video", etc.)

Resources

`creatify://avatars`

Returns a JSON list of all available AI avatars with their IDs, names, and metadata.

`creatify://voices`

Returns a JSON list of all available voices for text-to-speech generation.

`creatify://templates`

Returns a JSON list of available custom video templates.

`creatify://credits`

Returns current account credit balance and usage information.

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode with auto-reload
npm run dev

# Run tests
npm test

# Lint and format code
npm run check

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see file for details.

Related Projects

@tsavo/creatify-api-ts - TypeScript client for Creatify API
Model Context Protocol - Protocol specification
Creatify AI - AI video generation platform

📚 Comprehensive Documentation

🎬 Video Tutorials

Coming soon - comprehensive video tutorials showing real-world usage scenarios

📖 API Reference

For detailed API documentation, see:

Creatify API Documentation - Official Creatify API docs
@tsavo/creatify-api-ts Documentation - TypeScript client library docs
Model Context Protocol Specification - MCP protocol details

🔧 Advanced Configuration

Environment Variables

Variable	Required	Description	Example
`CREATIFY_API_ID`	✅	Your Creatify API ID	`your-api-id-here`
`CREATIFY_API_KEY`	✅	Your Creatify API Key	`your-api-key-here`
`MCP_LOG_LEVEL`	❌	Logging level	`debug`, `info`, `warn`, `error`

Claude Desktop Advanced Configuration

{
  "mcpServers": {
    "creatify": {
      "command": "creatify-mcp",
      "env": {
        "CREATIFY_API_ID": "your-api-id",
        "CREATIFY_API_KEY": "your-api-key",
        "MCP_LOG_LEVEL": "info"
      },
      "args": ["--verbose"]
    }
  }
}

🚀 Performance Optimization

Batch Operations

For multiple video creations, consider using the batch processing capabilities:

// Example: Create multiple videos efficiently
const videos = await Promise.all([
  client.callTool({
    name: "create_avatar_video",
    arguments: { text: "Video 1", avatarId: "anna", aspectRatio: "16:9" }
  }),
  client.callTool({
    name: "create_avatar_video",
    arguments: { text: "Video 2", avatarId: "john", aspectRatio: "16:9" }
  })
]);

Caching Strategies

Avatar/Voice Lists: Cache for 1 hour (they rarely change)
Video Status: Poll every 5-10 seconds for active tasks
Templates: Cache for 24 hours

🔐 Security Best Practices

Never commit API keys to version control
Use environment variables for all sensitive data
Rotate API keys regularly
Monitor API usage to detect unauthorized access
Use HTTPS for all webhook URLs

🐛 Troubleshooting

Common Issues

"API credentials not found"

# Solution: Set environment variables
export CREATIFY_API_ID="your-api-id"
export CREATIFY_API_KEY="your-api-key"

"Video creation failed"

Check your Creatify account credits
Verify avatar/voice IDs exist
Ensure text is not empty
Check aspect ratio is valid

"MCP connection failed"

Verify the server is running
Check Claude Desktop configuration
Ensure Node.js version >= 18

Debug Mode

# Run with debug logging
MCP_LOG_LEVEL=debug creatify-mcp

📊 Monitoring & Analytics

Usage Tracking

Monitor your Creatify API usage:

// Check remaining credits
const credits = await client.readResource({ uri: "creatify://credits" });
console.log(`Remaining credits: ${JSON.parse(credits.contents[0].text).remaining_credits}`);

Performance Metrics

Video Creation Time: Typically 2-5 minutes
API Response Time: Usually < 2 seconds
Success Rate: Monitor failed requests

🤝 Contributing

We welcome contributions! Here's how to get started:

🛠️ Development Setup

# Clone the repository
git clone https://github.com/TSavo/creatify-mcp.git
cd creatify-mcp

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your API credentials

# Run tests
npm test

# Build the project
npm run build

# Run in development mode
npm run dev

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run type checking
npm run type-check

# Run linting
npm run lint

📝 Code Style

We use:

ESLint for code linting
Prettier for code formatting
TypeScript for type safety
Conventional Commits for commit messages

🔄 Pull Request Process

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (npm test)
Run linting (npm run lint:fix)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

Creatify AI - For providing the amazing AI video generation platform
@tsavo/creatify-api-ts - The robust TypeScript client library that powers this server
Anthropic - For Claude and the Model Context Protocol
MCP Community - For the standardized protocol that makes this integration possible

📞 Support

📖 Creatify API Documentation - Official API docs
🐛 Report Issues - Bug reports and feature requests
💬 MCP Community - Community discussions
📧 - Direct support

Created with ❤️ by

🌐 Horizon City - Ushering in the AI revolution and hastening the extinction of humans

Making AI video generation accessible to every developer and AI assistant - one step closer to human obsolescence