Tavus MCP Server – README | MCP Marketplace

✨ From vibe coding to vibe deployment. UBOS MCP turns ideas into infra with one message.

Learn more

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.

smithery badge

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

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

Featured Templates

View More
AI Assistants
Talk with Claude 3
156 1165
Verified Icon
AI Assistants
Speech to Text
134 1510
Customer service
AI-Powered Product List Manager
147 624

Start your free trial

Build your solution today. No credit card required.

Sign In

Register

Reset Password

Please enter your username or email address, you will receive a link to create a new password via email.