README.md•21 kB
# 🎬 Creatify MCP Server
[](https://www.npmjs.com/package/@tsavo/creatify-mcp)
[](https://www.npmjs.com/package/@tsavo/creatify-mcp)
[](https://github.com/TSavo/creatify-mcp/actions/workflows/ci.yml)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://creatify.ai)
[](https://opensource.org/licenses/MIT)
[](https://github.com/TSavo/creatify-mcp)
[](https://github.com/TSavo/creatify-mcp/issues)
[](https://github.com/semantic-release/semantic-release)
> **The ultimate MCP server for AI video generation** - Bringing [Creatify AI](https://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`](https://www.npmjs.com/package/@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](https://creatify.ai/api)** - The world's leading AI video generation platform
- **[@tsavo/creatify-api-ts](https://www.npmjs.com/package/@tsavo/creatify-api-ts)** - Comprehensive TypeScript client library
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - 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](https://app.creatify.ai/account)
## Installation
### From npm (recommended)
```bash
npm install -g @tsavo/creatify-mcp
```
### From source
```bash
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:
```bash
export CREATIFY_API_ID="your-api-id"
export CREATIFY_API_KEY="your-api-key"
```
Or create a `.env` file:
```env
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):
```json
{
"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
```typescript
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
```bash
# 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
```bash
# 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
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Related Projects
- [`@tsavo/creatify-api-ts`](https://github.com/TSavo/creatify-api-ts) - TypeScript client for Creatify API
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol specification
- [Creatify AI](https://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](https://creatify.ai/api)** - Official Creatify API docs
- **[@tsavo/creatify-api-ts Documentation](https://github.com/TSavo/creatify-api-ts#readme)** - TypeScript client library docs
- **[Model Context Protocol Specification](https://modelcontextprotocol.io/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
```json
{
"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:
```typescript
// 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
1. **Never commit API keys** to version control
2. **Use environment variables** for all sensitive data
3. **Rotate API keys** regularly
4. **Monitor API usage** to detect unauthorized access
5. **Use HTTPS** for all webhook URLs
### 🐛 Troubleshooting
#### Common Issues
**"API credentials not found"**
```bash
# 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
```bash
# Run with debug logging
MCP_LOG_LEVEL=debug creatify-mcp
```
### 📊 Monitoring & Analytics
#### Usage Tracking
Monitor your Creatify API usage:
```typescript
// 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
```bash
# 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
```bash
# 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
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`npm test`)
6. Run linting (`npm run lint:fix`)
7. Commit your changes (`git commit -m 'feat: add amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **[Creatify AI](https://creatify.ai)** - For providing the amazing AI video generation platform
- **[@tsavo/creatify-api-ts](https://www.npmjs.com/package/@tsavo/creatify-api-ts)** - The robust TypeScript client library that powers this server
- **[Anthropic](https://www.anthropic.com)** - For Claude and the Model Context Protocol
- **[MCP Community](https://github.com/modelcontextprotocol)** - For the standardized protocol that makes this integration possible
## 📞 Support
- 📖 **[Creatify API Documentation](https://creatify.ai/api)** - Official API docs
- 🐛 **[Report Issues](https://github.com/TSavo/creatify-mcp/issues)** - Bug reports and feature requests
- 💬 **[MCP Community](https://github.com/modelcontextprotocol/specification/discussions)** - Community discussions
- 📧 **[Contact Author](mailto:listentomy@nefariousplan.com)** - Direct support
---
<div align="center">
**Created with ❤️ by [T Savo](mailto:listentomy@nefariousplan.com)**
🌐 **[Horizon City](https://www.horizon-city.com)** - *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*
</div>