MCP MiniMax Music Server

MCP MiniMax Music Server

一个使用 MiniMax Music API 进行 AI 音频生成的 Model Context Protocol（MCP）服务实现。由 Falah.G.Salieh 开发。

📋 目录

• 概述
• 功能
• 前置条件
• 安装
• 配置
• 使用方法
• API 参考
• 故障排除
• 贡献
• 许可证
• 作者

🎯 概述

此 MCP 服务通过 Model Context Protocol，让 AI Agent 能够使用 MiniMax Music API 生成音乐和音频内容。它可与 Claude Desktop 等 MCP 主机无缝集成，让 AI Agent 根据文本提示词创作音乐和音频。

✨ 功能

• AI 驱动的音乐生成
• 支持 MiniMax Music 模型
• 两步生成流程，支持状态检查
• 与 Claude Desktop 无缝集成
• 支持通过环境变量配置 API 密钥
• 详细的错误处理和报告

🔧 前置条件

• Node.js（v16 或更高版本）
• TypeScript（v5.3.3 或更高版本）
• Claude Desktop（最新版本）
• AIML API 密钥
• Windows/Linux/macOS 操作系统

📦 安装

1. 克隆代码库：

   git clone https://github.com/yourusername/mcp-minimax-music-server.git
   cd mcp-minimax-music-server
   

2. 安装依赖项：

   npm install
   

3. 构建服务：

   npm run build
   

⚙️ 配置

Claude Desktop 配置

1. 找到 Claude Desktop 配置文件：

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

2. 添加以下配置：

   {
     "mcpServers": {
       "minimax-music-server": {
         "command": "node",
         "args": [
           "G:\\mcp-minimax-music-server\\build\\index.js"
         ],
         "env": {
           "AIML_API_KEY": "Bearer your-aiml-api-key-here"
         }
       }
     }
   }
   

   ⚠️ 重要：

   • 将路径替换为实际的服务路径
   • 在 API 密钥前添加 "Bearer " 前缀
   • Windows 路径中使用双反斜杠

API 密钥设置

可以通过以下两种方式配置 AIML API 密钥：

1. 环境变量（推荐）

   • 按照上文所示，在 Claude Desktop 配置中设置
   • 添加 "Bearer " 前缀（包括空格）
   • 示例："AIML_API_KEY": "Bearer 3d90d64a000c4e6eb02df7e52d2166d2"

2. 直接配置

   • 在生成请求中直接传入 API 密钥
   • 安全性较低，但适合测试

🚀 使用方法

基本用法

此服务提供名为 generate_audio 的工具，参数如下：

• prompt（必填）：用于音频生成的文本提示词
• model（可选）：设为 "minimax-music"
• reference_audio_url（可选）：参考音频的 URL
• generation_id（可选）：用于检查状态的先前生成 ID

示例命令

1. 开始新的生成任务：

   Generate audio with prompt "Create a romantic love song with gentle acoustic guitar and soft vocals"
   

2. 检查生成状态：

   Generate audio with generation_id "abc123" and prompt "Check status"
   

响应格式

{
  "toolResult": {
    "status": "completed",
    "id": "generation-id",
    "audio_file": {
      "url": "https://cdn.example.com/audio.mp3",
      "content_type": "audio/mpeg",
      "file_name": "output.mp3",
      "file_size": 1024000
    }
  }
}

📚 API 参考

MiniMax Music 模型

此服务使用 MiniMax Music 模型，该模型：

• 专用于音乐生成
• 需要参考音频来匹配风格
• 支持使用 ## 分隔符生成歌词
• 可生成高品质音乐

生成流程

1. 步骤 1：提交生成请求

   • 发送提示词和参数
   • 获取生成 ID

2. 步骤 2：检查状态

   • 使用生成 ID 轮询状态
   • 完成后下载音频

🔍 故障排除

常见问题

1. 身份验证错误（401）

   • 确认 API 密钥格式正确（应以 "Bearer " 开头）
   • 检查 API 密钥是否有效
   • 确认 claude_desktop_config.json 中的配置正确

2. 路径问题

   • 使用适合当前操作系统的路径格式
   • Windows：使用双反斜杠
   • 确认构建目录存在

3. 生成错误

   • 检查提示词格式（歌词应使用 ##...## 包裹）
   • 确保可以访问参考音频 URL
   • 检查提示词长度和内容

调试步骤

1. 重新构建服务：

   npm run build
   

2. 重启 Claude Desktop

3. 检查服务日志中的错误

🤝 参与贡献

1. Fork 该仓库
2. 创建功能分支
3. 提交更改
4. 推送到该分支
5. 创建 Pull Request

📄 许可证

MIT License - 详情请参阅 LICENSE 文件

👤 作者

Falah.G.Salieh

• 所在地：Baghdad, Iraq
• 职务：开发者和 AI 集成专家
• 年份：2025

🌟 支持

需要帮助？以下是获取支持的方式：

1. 查看故障排除部分
2. 在该仓库中提交问题
3. 直接联系作者

---

本项目属于 Model Context Protocol 生态系统，可实现 AI Agent 与外部服务之间的无缝集成。