内容
# Hedra MCP 服务器
[](https://www.npmjs.com/package/mcp-server-hedra)
[](https://opensource.org/licenses/MIT)
Hedra AI 视频、音频和图像生成平台的模型上下文协议（MCP）服务器。该服务器使 Claude 等 AI 助手能够使用 Hedra 的强大 AI 模型（包括 Character-3、Veo 3.1、Sora 2、Kling 和 MiniMax）生成视频、图像和音频。
## 功能
- **视频生成**：从文本提示和图像创建 AI 生成的视频
- **文本转语音**：从文本生成自然语音，支持自定义声音
- **图像生成**：从文本描述创建图像
- **资产管理**：上传和管理图像、音频和视频资产
- **生成跟踪**：监控生成作业的状态和进度
- **信用管理**：查看您的信用余额和使用情况
## 先决条件
- Node.js 18.0.0 或更高版本
- 具有 API 访问权限的 Hedra 账户（Creator 计划或以上）
- 从 [https://hedra.com/api-profile](https://hedra.com/api-profile) 获取 Hedra API 密钥
## 安装
### 使用 npx（推荐）
```bash
npx mcp-server-hedra
```
### 全局安装
```bash
npm install -g mcp-server-hedra
```
### 从源代码安装
```bash
git clone https://github.com/your-username/mcp-server-hedra.git
cd mcp-server-hedra
npm install
npm run build
```
## 配置
### 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `HEDRA_API_KEY` | 是 | - | 您的 Hedra API 密钥 |
| `HEDRA_BASE_URL` | 否 | `https://api.hedra.com/web-app/public` | API 基本 URL |
| `HEDRA_TIMEOUT` | 否 | `60000` | 请求超时时间（毫秒） |
### 身份验证
Hedra API 使用在 `X-API-Key` 头部传递的 API 密钥：
```
X-API-Key: <您的 API 密钥>
```
从 [https://hedra.com/api-profile](https://hedra.com/api-profile) 获取您的 API 密钥（需要 Creator 计划或以上）。
### Claude Desktop 配置
将以下内容添加到您的 Claude Desktop 配置文件中：
**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": "您的 API 密钥"
}
}
}
}
```
### Cline（VS Code）配置
```json
{
"mcpServers": {
"hedra": {
"command": "npx",
"args": ["mcp-server-hedra"],
"env": {
"HEDRA_API_KEY": "您的 API 密钥"
}
}
}
}
```
## 可用工具
### `list_models`
列出可用于视频、音频和图像生成的 AI 模型。
```json
{
"types": ["video"] // 可选：按模型类型过滤
}
```
### `list_assets`
列出用户资产，包括图像、音频、视频和语音文件。
```json
{
"type": "image" // 必需：文本、图像、音频、视频、语音
}
```
### `create_asset`
为上传文件创建新的资产占位符。
```json
{
"name": "my-image.png",
"type": "image"
}
```
### `upload_asset`
将文件上传到现有的资产。
```json
{
"id": "asset-uuid",
"file_base64": "base64-encoded-content",
"filename": "image.png"
}
```
### `generate_video`
从文本提示、图像和可选音频生成视频。
```json
{
"ai_model_id": "model-uuid",
"text_prompt": "一个人对着摄像头说话",
"start_keyframe_id": "image-asset-uuid",
"audio_id": "audio-asset-uuid",
"resolution": "720p",
"aspect_ratio": "16:9",
"duration_ms": 5000
}
```
### `generate_video_with_tts`
一步生成视频和文本转语音音频。
```json
{
"ai_model_id": "model-uuid",
"text_prompt": "一个人说话",
"start_keyframe_id": "image-asset-uuid",
"voice_id": "voice-uuid",
"speech_text": "你好，欢迎来到我的视频！",
"resolution": "720p",
"aspect_ratio": "9:16"
}
```
### `generate_text_to_speech`
使用文本转语音功能从文本生成音频。
```json
{
"voice_id": "voice-uuid",
"text": "你好，这是测试。",
"stability": 0.8,
"speed": 1.0
}
```
### `generate_image`
从文本提示生成图像。
```json
{
"text_prompt": "山脉上美丽的日落",
"aspect_ratio": "16:9",
"seed": 12345
}
```
### `get_generation_status`
获取生成作业的状态。
```json
{
"generation_id": "generation-uuid"
}
```
### `get_credits`
获取当前信用余额和使用情况信息。
```json
{}
```
### `list_generations`
列出生成作业，支持过滤和分页。
```json
{
"type": "video",
"limit": 50,
"offset": 0
}
```
## 使用示例
### 生成对话视频
1. 首先，列出可用的模型：
```
使用 list_models 查看可用的视频模型
```
2. 上传人像图像：
```
创建图像资产并上传人像照片
```
3. 生成视频：
```
使用 Character-3 模型生成视频，上传图像和文本 "一个人微笑和挥手"
```
4. 检查状态：
```
检查生成状态以获取下载 URL
```
### 生成图像
```
生成图像，提示 "一个有霓虹灯的赛博朋克城市在夜间"
```
## 支持的模型
Hedra 支持多个 AI 模型，包括：
- **Character-3**：Hedra 的唇同步视频生成模型
- **Veo 3.1**：Google 的视频生成模型
- **Sora 2 Pro**：OpenAI 的视频生成模型
- **Kling 2.6 Pro**：具有强大运动的视频生成模型
- **MiniMax Hailuo**：快速视频生成模型
使用 `list_models` 查看当前所有可用的模型及其功能。
## 信用成本
视频生成的信用成本根据模型不同而有所不同：
- Veo 3.1 Fast：20 信用点
- Veo 3.1：55 信用点
- Sora 2 Pro：70 信用点
- Kling 2.6 Pro：20 信用点
- Kling 2.5 Turbo：10 信用点
- MiniMax Hailuo 2.3 Fast Pro：7 信用点
使用 `get_credits` 查看您当前的信用余额。
## 错误处理
服务器为常见问题提供清晰的错误消息：
- **401/403**：身份验证失败 - 检查您的 API 密钥
- **404**：资源未找到 - 验证资产/生成 ID
- **422**：参数无效 - 检查请求格式
- **429**：速率限制已超过 - 请等待重试
## 开发
```bash
# 安装依赖
npm install
# 构建
npm run build
# 监视模式
npm run dev
# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector node dist/index.js
```
## 故障排除
### "HEDRA_API_KEY 环境变量是必需的"
确保您的 API 密钥已在配置文件或环境中设置。
### "身份验证失败"
验证您的 API 密钥是否在 [https://hedra.com/api-profile](https://hedra.com/api-profile) 处有效。
### 生成卡在 "processing" 状态
视频生成可能需要几分钟。使用 `get_generation_status` 监控进度。
## 资源
- [Hedra 网站](https://hedra.com)
- [Hedra API 文档](https://www.hedra.com/docs/pages/getting_started/quickstart)
- [Hedra API 启动工具](https://github.com/hedra-labs/hedra-api-starter)
- [模型上下文协议](https://modelcontextprotocol.io)
## 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE) 文件了解详情。
