rakeshdavid/Tavus-MCP

Tavus MCP Server

A comprehensive Model Context Protocol (MCP) server for the Tavus API, enabling AI video generation, replica management, conversational AI, lipsync, and speech synthesis through MCP-compatible applications.

Features

🎭 Phoenix Replicas (5 tools)

• create_replica - Create new AI replicas from training videos
• get_replica - Get detailed information about a specific replica
• list_replicas - List all replicas in your account
• delete_replica - Delete a replica permanently
• rename_replica - Rename an existing replica

🎬 Video Generation (5 tools)

• generate_video - Generate videos using replicas with text scripts or audio files
• get_video - Get details of a specific video
• list_videos - List all videos in your account
• delete_video - Delete a video permanently
• rename_video - Rename an existing video

💬 Conversational AI (5 tools)

• create_conversation - Create interactive video conversations
• get_conversation - Get details of a specific conversation
• list_conversations - List all conversations in your account
• end_conversation - End an active conversation
• delete_conversation - Delete a conversation permanently

👤 Personas (5 tools)

• create_persona - Create new personas for conversational AI
• get_persona - Get details of a specific persona
• list_personas - List all personas in your account
• patch_persona - Update a persona using JSON patch format
• delete_persona - Delete a persona permanently

🎵 Lipsync (4 tools)

• create_lipsync - Synchronize audio with existing videos
• get_lipsync - Get details of a specific lipsync
• list_lipsyncs - List all lipsyncs in your account
• delete_lipsync - Delete a lipsync permanently

🗣️ Speech Synthesis (5 tools)

• generate_speech - Generate speech audio from text using replicas
• get_speech - Get details of a specific speech
• list_speeches - List all speeches in your account
• delete_speech - Delete a speech permanently
• rename_speech - Rename an existing speech

Prerequisites

• Node.js 18+
• A Tavus API key (get one at platform.tavus.io)

Installation

Installing via Smithery

To install tavus-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @rakeshdavid/tavus-mcp --client claude

Option 1: NPM Package (Recommended)

npm install -g tavus-mcp

Option 2: From Source

git clone https://github.com/rakeshdavid/Tavus-MCP.git
cd Tavus-MCP
npm install
npm run build

Configuration

Environment Variables

Set your Tavus API key as an environment variable:

export TAVUS_API_KEY="your_tavus_api_key_here"

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tavus-mcp": {
      "command": "npx",
      "args": ["tavus-mcp"],
      "env": {
        "TAVUS_API_KEY": "your_tavus_api_key_here"
      }
    }
  }
}

Cline (VS Code Extension)

Add to your Cline MCP settings:

{
  "mcpServers": {
    "tavus-mcp": {
      "command": "npx",
      "args": ["tavus-mcp"],
      "env": {
        "TAVUS_API_KEY": "your_tavus_api_key_here"
      },
      "disabled": false
    }
  }
}

Other MCP Clients

For other MCP-compatible applications, use:

npx tavus-mcp

With the TAVUS_API_KEY environment variable set.

Usage Examples

Once configured, you can use the Tavus tools through your MCP client:

List Your Replicas

"Can you list my Tavus replicas?"

Generate a Video

"Generate a video using replica 'Luna' with the script: 'Hello, welcome to our product demo!'"

Create a Conversational AI

"Create a new conversational AI persona using my replica for customer support"

Lipsync Audio to Video

"Create a lipsync video using this video URL and this audio URL"

API Coverage

This MCP server provides complete coverage of the Tavus API v2, including:

• Phoenix Replicas: Full CRUD operations for AI video replicas
• Video Generation: Text-to-video and audio-to-video generation with advanced customization
• Conversational AI: Interactive video conversations with persona management
• Lipsync: Audio synchronization with existing videos
• Speech Synthesis: Text-to-speech generation using replicas

Development

Setup

git clone https://github.com/rakeshdavid/Tavus-MCP.git
cd Tavus-MCP
npm install

Build

npm run build

Development with Auto-rebuild

npm run watch

Testing

Set your API key and test the server:

export TAVUS_API_KEY="your_api_key"
npm run inspector

The MCP Inspector will provide a URL to test the server in your browser.

Error Handling

The server includes comprehensive error handling:

• Authentication errors: Invalid API key
• Rate limiting: API rate limit exceeded
• Payment errors: Insufficient credits (402 status)
• Validation errors: Invalid parameters
• Network errors: Connection issues

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

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

Support

• Documentation: Tavus API Documentation
• Issues: GitHub Issues
• MCP Protocol: Model Context Protocol

Changelog

v0.1.0

• Initial release
• Complete Tavus API v2 coverage
• 25 tools across 5 categories
• TypeScript implementation
• Comprehensive error handling