MMAudio

MMAudio MCP

使用 MMAudio 的先进 AI 技术，实现 AI 驱动的视频转音频和文本转音频生成。此桌面扩展实现了模型上下文协议（MCP），可与 Cursor、Claude Desktop 和其他兼容 MCP 的客户端无缝集成。

🌟 功能

• 视频转音频生成：通过 AI 驱动的分析，将视频内容转换为同步音频
• 文本转音频生成：根据文本描述创作专业音频内容
• API 密钥验证：验证 MMAudio API 凭据并检查账户状态
• MCP 协议：完整实现模型上下文协议，确保普遍兼容性
• 错误处理：全面的错误处理，并提供详细反馈
• 类型安全：完整支持 TypeScript，并使用 Zod 架构验证
• 可配置：提供灵活的配置选项，适用于不同用例

🚀 快速开始

前提条件

• Node.js >= 18.0.0
• MMAudio API 密钥（点击此处获取）
• 兼容 MCP 的客户端（Cursor、Claude Desktop 等）

安装

1. 克隆或下载此扩展：

   cd mcp
   npm install
   

2. 配置 API 密钥：

   # Set environment variable
   export MMAUDIO_API_KEY="sk-your-api-key-here"
   
   # Or create a config.js file (copy from config.example.js)
   cp config.example.js config.js
   # Edit config.js with your API key
   

3. 测试安装：

   npm start
   

4. 链接软件包：

   npm link
   

在 Cursor 中使用

1. 添加到 Cursor MCP 配置：

   {
     "mcpServers": {
       "mmaudio": {
         "command": "npx",
         "args": ["-y", "mmaudio-mcp@latest"],
         "env": {
           "MMAUDIO_API_KEY": "sk-your-api-key-here"
         }
       }
     }
   }
   

2. 重启 Cursor，即可在 AI 助手中使用 MMAudio 工具。

在 Claude Desktop 中使用

1. 添加到 Claude Desktop 配置（claude_desktop_config.json）：

   {
     "mcpServers": {
       "mmaudio": {
         "command": "npx",
         "args": ["-y", "mmaudio-mcp@latest"],
         "env": {
           "MMAUDIO_API_KEY": "sk-your-api-key-here"
         }
       }
     }
   }
   

2. 重启 Claude Desktop 以加载扩展。

🛠️ 可用工具

1. 视频转音频生成

根据视频内容生成 AI 音频。

工具名称：video_to_audio

参数：

• video_url（必填）：视频文件的 URL
• prompt（必填）：对所需生成音频的描述
• negative_prompt（可选）：生成音频中需要避免的内容
• duration（可选）：音频时长（秒）（1-30，默认值：8）
• num_steps（可选）：推理步数（1-50，默认值：25）
• cfg_strength（可选）：引导强度（1-10，默认值：4.5）
• seed（可选）：用于复现结果的随机种子

示例：

Generate audio for this video: https://example.com/video.mp4 with the prompt "peaceful forest sounds with birds chirping and gentle wind"

2. 文本转音频生成

根据文本描述创作音频内容。

工具名称：text_to_audio

参数：

• prompt（必填）：对所需生成音频的描述
• duration（可选）：音频时长（秒）（1-30，默认值：8）
• num_steps（可选）：推理步数（1-50，默认值：25）
• cfg_strength（可选）：引导强度（1-10，默认值：4.5）
• negative_prompt（可选）：生成音频中需要避免的内容
• seed（可选）：用于复现结果的随机种子

示例：

Create audio with the description "coffee shop ambiance with gentle chatter and espresso machine sounds"

3. API 密钥验证

验证 MMAudio API 密钥并检查账户状态。

工具名称：validate_api_key

参数：

• api_key（可选）：要验证的 API 密钥（如果未提供，则使用已配置的密钥）

示例：

Validate my MMAudio API key

⚙️ 配置

环境变量

变量	描述	必填	默认值
MMAUDIO_API_KEY	您的 MMAudio API 密钥	是	-
MMAUDIO_BASE_URL	MMAudio API 的基础 URL	否	https://mmaudio.net
MMAUDIO_TIMEOUT	请求超时时间（毫秒）	否	60000
LOG_LEVEL	日志级别（error、warn、info、debug）	否	error
DEBUG	启用调试模式	否	false

配置文件

您也可以使用 config.js 文件进行配置：

export const config = {
  apiKey: "sk-your-api-key-here",
  baseUrl: "https://mmaudio.net",
  timeout: 60000,
  // ... other options
};

📝 使用示例

视频转音频示例

// In your MCP client (Cursor, Claude Desktop, etc.)
"Please generate audio for this video URL: https://example.com/nature_video.mp4";
"I want forest sounds with birds chirping and a gentle breeze";
"Duration should be 10 seconds";

文本转音频示例

// Create ambient audio
"Generate 15 seconds of coffee shop ambiance with gentle background chatter";

// Create sound effects
"Create the sound of rain falling on a wooden roof for 8 seconds";

// Create atmospheric audio
"Generate futuristic sci-fi ambient sounds for a space station";

🔧 开发

项目结构

mcp/
├── server/index.js              # Main MCP server implementation
├── package.json           # Node.js dependencies and scripts
├── manifest.json          # DXT extension manifest
├── config.example.js      # Configuration example
└── README.md              # This file

测试

1. 直接测试服务：

   npm start
   

2. 使用简单的 MCP 客户端测试：

   echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | npm start
   

开发模式

在开发模式下运行服务并启用调试：

npm run dev

这会启用额外的日志记录和 Node.js 检查器，以便进行调试。

🚨 故障排除

常见问题

1. “API key is required”错误

问题：扩展程序无法找到您的 API 密钥。

解决方案：

• 确保已设置 MMAUDIO_API_KEY 环境变量
• 或创建包含 API 密钥的 config.js 文件
• 确认 API 密钥正确且有效

2. “Connection refused”或网络错误

问题：无法连接到 MMAudio API。

解决方案：

• 检查您的网络连接
• 确认基础 URL 正确
• 检查是否存在防火墙限制

3. “Insufficient credits”错误

问题：您的 MMAudio 账户余额不足。

解决方案：

• 在 mmaudio.net/dashboard 查看账户余额
• 如有需要，购买额外额度
• 使用 validate_api_key 工具检查账户状态

4. MCP 客户端未检测到扩展程序

问题：您的 MCP 客户端（Cursor、Claude Desktop）未显示 MMAudio 工具。

解决方案：

• 检查 MCP 客户端设置中的配置路径
• 确保 Node.js 位于 PATH 中
• 检查服务日志中的错误
• 重启 MCP 客户端

调试模式

启用调试模式以查看详细日志：

DEBUG=true MMAUDIO_API_KEY=your-key node server/index.js

日志

服务会将日志写入 stderr。您可以将日志重定向到文件：

node server/index.js 2> mmaudio.log

📄 API 参考

响应格式

所有工具均按以下格式返回响应：

{
  "content": [
    {
      "type": "text",
      "text": "{\"success\": true, \"message\": \"...\", \"result\": {...}}"
    }
  ]
}

成功响应示例

{
  "success": true,
  "message": "Audio generated successfully from text",
  "result": {
    "audio_url": "https://example.com/generated_audio.wav",
    "content_type": "audio/wav",
    "file_name": "generated_audio.wav",
    "file_size": 1024000,
    "duration": 8,
    "prompt": "coffee shop ambiance"
  }
}

错误响应示例

{
  "success": false,
  "error": "Invalid API key. Please check your MMAudio API key.",
  "code": "INVALID_REQUEST"
}

🔒 安全

• API 密钥会得到安全处理，不会记录在日志中
• 所有请求均使用 HTTPS
• 扩展程序在沙盒环境中运行
• 不会在本地存储敏感数据

📖 相关文档

• MMAudio API 文档
• 模型上下文协议规范
• Cursor MCP 集成指南
• Claude Desktop MCP 设置

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 根据需要添加测试
5. 提交拉取请求

📝 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

💬 支持

• MMAudio 支持
• GitHub 问题
• 文档

---

由 MMAudio 团队倾情打造 ❤️