Hedra MCP Server

A Model Context Protocol (MCP) server for the Hedra AI video, audio, and image generation platform. This server enables AI assistants like Claude to generate videos, images, and audio using Hedra's powerful AI models including Character-3, Veo 3.1, Sora 2, Kling, and MiniMax.

Features

• Video Generation: Create AI-generated videos from text prompts and images
• Text-to-Speech: Generate natural speech from text with customizable voices
• Image Generation: Create images from text descriptions
• Asset Management: Upload and manage images, audio, and video assets
• Generation Tracking: Monitor the status and progress of generation jobs
• Credit Management: Check your credit balance and usage

Prerequisites

• Node.js 18.0.0 or higher
• A Hedra account with API access (Creator plan or above)
• Hedra API key from https://hedra.com/api-profile

Installation

Using npx (Recommended)

npx mcp-server-hedra

Global Installation

npm install -g mcp-server-hedra

From Source

git clone https://github.com/your-username/mcp-server-hedra.git
cd mcp-server-hedra
npm install
npm run build

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | HEDRA_API_KEY | Yes | - | Your Hedra API key | | HEDRA_BASE_URL | No | https://api.hedra.com/web-app/public | API base URL | | HEDRA_TIMEOUT | No | 60000 | Request timeout in milliseconds |

Authentication

The Hedra API uses an API key passed in the X-API-Key header:

X-API-Key: <your-api-key>

Get your API key from https://hedra.com/api-profile (requires Creator plan or above).

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "hedra": {
      "command": "npx",
      "args": ["mcp-server-hedra"],
      "env": {
        "HEDRA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cline (VS Code) Configuration

{
  "mcpServers": {
    "hedra": {
      "command": "npx",
      "args": ["mcp-server-hedra"],
      "env": {
        "HEDRA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

list_models

Lists available AI models for video, audio, and image generation.

{
  "types": ["video"]  // Optional: filter by model type
}

list_assets

Lists user assets including images, audio, video, and voice files.

{
  "type": "image"  // Required: text, image, audio, video, voice
}

create_asset

Creates a new asset placeholder for uploading files.

{
  "name": "my-image.png",
  "type": "image"
}

upload_asset

Uploads a file to an existing asset.

{
  "id": "asset-uuid",
  "file_base64": "base64-encoded-content",
  "filename": "image.png"
}

generate_video

Generates a video from text prompt, image, and optional audio.

{
  "ai_model_id": "model-uuid",
  "text_prompt": "A person talking to the camera",
  "start_keyframe_id": "image-asset-uuid",
  "audio_id": "audio-asset-uuid",
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "duration_ms": 5000
}

generate_video_with_tts

Generates a video with text-to-speech audio in one call.

{
  "ai_model_id": "model-uuid",
  "text_prompt": "A person talking",
  "start_keyframe_id": "image-asset-uuid",
  "voice_id": "voice-uuid",
  "speech_text": "Hello, welcome to my video!",
  "resolution": "720p",
  "aspect_ratio": "9:16"
}

generate_text_to_speech

Generates audio from text using text-to-speech.

{
  "voice_id": "voice-uuid",
  "text": "Hello, this is a test.",
  "stability": 0.8,
  "speed": 1.0
}

generate_image

Generates an image from a text prompt.

{
  "text_prompt": "A beautiful sunset over mountains",
  "aspect_ratio": "16:9",
  "seed": 12345
}

get_generation_status

Gets the status of a generation job.

{
  "generation_id": "generation-uuid"
}

get_credits

Gets the current credit balance and usage information.

{}

list_generations

Lists generation jobs with filtering and pagination.

{
  "type": "video",
  "limit": 50,
  "offset": 0
}

Usage Examples

Generate a Talking Head Video

1. First, list available models:

Use list_models to see available video models

2. Upload a portrait image:

Create an image asset and upload a portrait photo

3. Generate a video:

Generate a video using Character-3 model with the uploaded image and text "A person smiling and waving"

4. Check the status:

Check the generation status to get the download URL

Generate an Image

Generate an image with the prompt "A cyberpunk city at night with neon lights"

Supported Models

Hedra supports multiple AI models including:

• Character-3: Hedra's lip-sync video generation model
• Veo 3.1: Google's video generation model
• Sora 2 Pro: OpenAI's video generation model
• Kling 2.6 Pro: Video generation with strong motion
• MiniMax Hailuo: Fast video generation

Use list_models to see all currently available models and their capabilities.

Credit Costs

Video generation costs vary by model:

• Veo 3.1 Fast: 20 credits
• Veo 3.1: 55 credits
• Sora 2 Pro: 70 credits
• Kling 2.6 Pro: 20 credits
• Kling 2.5 Turbo: 10 credits
• MiniMax Hailuo 2.3 Fast Pro: 7 credits

Use get_credits to check your current balance.

Error Handling

The server provides clear error messages for common issues:

• 401/403: Authentication failed - check your API key
• 404: Resource not found - verify asset/generation IDs
• 422: Invalid parameters - check request format
• 429: Rate limit exceeded - wait before retrying

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Troubleshooting

"HEDRA_API_KEY environment variable is required"

Ensure your API key is set in the configuration or environment.

"Authentication failed"

Verify your API key is valid at https://hedra.com/api-profile.

Generation stuck in "processing"

Video generation can take several minutes. Use get_generation_status to monitor progress.

Resources

• Hedra Website
• Hedra API Documentation
• Hedra API Starter Kit
• Model Context Protocol

License

MIT License - see LICENSE file for details.