VidMax MCP Server

A Model Context Protocol (MCP) server that exposes VidMax API endpoints for use with AI assistants like Claude.

Features

This MCP server provides tools for:

• Health Monitoring: Check API health status
• Video Management: Create, retrieve, and render videos
• Series Management: Create and manage video series
• Image Generation: Generate AI images from prompts
• Voice Operations: Manage voices and create voiceovers
• User & Team Info: Access account and team information

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g @aixlabs/vidmax-mcp-server

# Or run directly with npx
npx @aixlabs/vidmax-mcp-server

Option 2: Local Development

cd packages/vidmax-mcp-server
pnpm install
pnpm build

Configuration

Set the following environment variables:

# Required: Your VidMax API key
export VIDMAX_API_KEY="your-api-key-here"

# Optional: Custom API base URL (defaults to https://dev.vidmax.ai/api/v1)
export VIDMAX_API_BASE_URL="https://dev.vidmax.ai/api/v1"

Usage

With Claude Code

Option 1: Using npm package (Recommended)

claude mcp add-json vidmax-mcp '{
    "command": "npx",
    "args": ["@aixlabs/vidmax-mcp-server"],
    "env": {
        "VIDMAX_API_KEY": "your-api-key-here",
        "VIDMAX_API_BASE_URL": "https://dev.vidmax.ai/api/v1"
    }
}'

Option 2: Local development build

claude mcp add-json vidmax-local '{
    "command": "node",
    "args": [
        "/Users/bansalshray/Desktop/Projects/ShrayBans/BansalVentures/aix-turborepo/packages/vidmax-mcp-server/dist/index.js"
    ],
    "env": {
        "VIDMAX_API_KEY": "vm_live_05b252cb33105aaab034c130a2154507_cda0d4f",
        "VIDMAX_API_BASE_URL": "http://localhost:3000/api/v1"
    }
}'

With Claude Desktop

Option 1: Using npm package (Recommended)

Add to your Claude Desktop config (~/Library/Application\ Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vidmax": {
      "command": "npx",
      "args": ["@aixlabs/vidmax-mcp-server"],
      "env": {
        "VIDMAX_API_KEY": "your-api-key-here",
        "VIDMAX_API_BASE_URL": "https://dev.vidmax.ai/api/v1"
      }
    }
  }
}

Option 2: Local development build

{
  "mcpServers": {
    "vidmax": {
      "command": "node",
      "args": ["/absolute/path/to/aix-turborepo/packages/vidmax-mcp-server/dist/index.js"],
      "env": {
        "VIDMAX_API_KEY": "your-api-key-here",
        "VIDMAX_API_BASE_URL": "https://dev.vidmax.ai/api/v1"
      }
    }
  }
}

Testing with MCP Inspector

npm run inspector

Then open http://localhost:4000 in your browser.

Available Tools

System Operations

• health_check - Check API health
• auth_check - Validate API key and authentication

Video Operations

• get_videos - List videos with filtering
• get_video - Get specific video details
• create_video - Create AI video from prompt
• create_reddit_video - Create video from Reddit post
• create_fake_text_video - Create video from conversation
• render_video - Render video to MP4

Series Operations

• get_series - List all series
• create_series - Create new series
• generate_series_video - Generate video for series

Image Operations

• generate_image - Generate AI image
• get_images - List generated images

Voice Operations

• get_voices - List available voices
• create_voiceover - Create voiceover from text

Account Operations

• get_user_info - Get user account info
• get_team_info - Get team information

Resources

• vidmax://api/endpoints - Complete API endpoint documentation
• vidmax://api/authentication - Authentication guide

Example Usage

Once connected to Claude, you can use commands like:

"Create a new video with the prompt 'A day in the life of a software developer'"

"Generate an image with the prompt 'Futuristic cityscape at sunset'"

"Get all my videos and show me their status"

"Create a new series called 'Tech Tutorials' for educational content"

Development

# Build the server
npm run build

# Watch for changes during development
npm run dev

# Start the server
npm start

# Test with MCP Inspector
npm run inspector

Error Handling

The server handles API errors gracefully and returns structured error responses. Common issues:

• Authentication Error: Check your API key is valid
• Network Error: Verify the API base URL is correct
• Rate Limiting: The API may rate limit requests
• Invalid Parameters: Check tool input parameters match the schema