Content
# Hedra MCP Server
[](https://www.npmjs.com/package/mcp-server-hedra)
[](https://opensource.org/licenses/MIT)
A Model Context Protocol (MCP) server for the [Hedra](https://hedra.com) 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](https://hedra.com/api-profile)
## Installation
### Using npx (Recommended)
```bash
npx mcp-server-hedra
```
### Global Installation
```bash
npm install -g mcp-server-hedra
```
### From Source
```bash
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](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`
```json
{
"mcpServers": {
"hedra": {
"command": "npx",
"args": ["mcp-server-hedra"],
"env": {
"HEDRA_API_KEY": "your-api-key-here"
}
}
}
}
```
### Cline (VS Code) Configuration
```json
{
"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.
```json
{
"types": ["video"] // Optional: filter by model type
}
```
### `list_assets`
Lists user assets including images, audio, video, and voice files.
```json
{
"type": "image" // Required: text, image, audio, video, voice
}
```
### `create_asset`
Creates a new asset placeholder for uploading files.
```json
{
"name": "my-image.png",
"type": "image"
}
```
### `upload_asset`
Uploads a file to an existing asset.
```json
{
"id": "asset-uuid",
"file_base64": "base64-encoded-content",
"filename": "image.png"
}
```
### `generate_video`
Generates a video from text prompt, image, and optional audio.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"text_prompt": "A beautiful sunset over mountains",
"aspect_ratio": "16:9",
"seed": 12345
}
```
### `get_generation_status`
Gets the status of a generation job.
```json
{
"generation_id": "generation-uuid"
}
```
### `get_credits`
Gets the current credit balance and usage information.
```json
{}
```
### `list_generations`
Lists generation jobs with filtering and pagination.
```json
{
"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
```bash
# 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](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](https://hedra.com)
- [Hedra API Documentation](https://www.hedra.com/docs/pages/getting_started/quickstart)
- [Hedra API Starter Kit](https://github.com/hedra-labs/hedra-api-starter)
- [Model Context Protocol](https://modelcontextprotocol.io)
## License
MIT License - see [LICENSE](LICENSE) file for details.
