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.

🚀 Quick Start

To start using the Tavus MCP Server, you need to meet the prerequisites, install the server, configure it, and then you can start using the provided tools.

✨ 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.

📦 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

📚 Documentation

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.

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 LICENSE 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.

💻 Usage Examples

Basic Usage

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

"Can you list my Tavus replicas?"

Advanced Usage

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"