Aimusic MCP Tool

🚀 🎵 MusicMCP.AI MCP Server

MusicMCP.AI MCP Server 是官方的模型上下文协议（MCP）服务器，可实现与先进的 AI 音乐生成平台的无缝交互。该服务器允许像 Claude Desktop、OpenAI Agents 等 MCP 客户端通过自然语言命令生成 AI 音乐。

✨ 主要特性

• 🎼 AI 音乐生成：使用 MusicMCP.AI 的先进 AI 模型，根据文本提示生成歌曲。
• 🎵 双生成模式：支持灵感模式和自定义模式。
• 🔗 直接下载链接：获取生成音乐的直接下载 URL。
• 🎹 乐器选项：可生成纯乐器音乐或带人声的完整歌曲。
• ✅ 信用余额检查：检查 API 密钥的有效性和剩余信用额度。
• 🏥 健康监测：检查 API 服务的健康状态。

🚀 快速开始

使用 Claude Desktop 快速上手

1. 获取 API 密钥：从 MusicMCP.AI 平台 获取 API 密钥。
2. 安装 uv：使用以下命令安装 Python 包管理器：

curl -LsSf https://astral.sh/uv/install.sh | sh

3. 配置 Claude：进入 Claude > 设置 > 开发者 > 编辑配置 > claude_desktop_config.json 并添加以下内容：

{
    "mcpServers": {
        "MusicMCP.AI": {
            "command": "uvx",
            "args": [
                "aimusic-mcp"
            ],
            "env": {
                "MUSICMCP_API_KEY": "<insert-your-api-key-here>",
                "MUSICMCP_API_URL": "https://www.musicmcp.ai/api",
                "TIME_OUT_SECONDS": "600"
            }
        }
    }
}

4. 重启 Claude：重启 Claude 应用程序，你将看到 4 个 MCP 工具 可用，这表明加载成功。

⚙️ 环境变量

🛠️ 可用工具

1. 🎼 生成提示歌曲（灵感模式）

根据简单的文本描述生成 AI 音乐。AI 会自动创建标题、歌词和风格。

• 费用：每次生成 5 个信用点（生成 2 首歌曲）
• 参数：
  • prompt (str)：音乐主题的简单描述（1 - 1200 个字符）
  • instrumental (bool)：是否仅生成纯乐器音乐
  • style (str, 可选)：音乐风格（例如，"ambient"、"pop"、"rock"）
• 示例提示：

"帮我生成一首关于宁静早晨的歌曲"
"想要一首表达思念的歌曲"
"创作一首关于友谊的音乐"

• 输出示例：

✅ 歌曲 1 生成成功！

📌 标题: 宁静的早晨
🆔 ID: c7630638-b8ba-4984-876b-6dd7e6eeb796
🔗 下载 URL: https://cdn.musicmcp.ai/songs/abc123.mp3
🖼️ 封面图片: https://cdn.musicmcp.ai/images/abc123.jpg
⏱️ 时长: 180 秒
🎵 风格标签: ambient, meditation, peaceful
🎹 纯乐器: 否
📅 创建时间: 2025-01-15T10:30:45.123Z
📝 歌词:
[主歌]
柔和的阳光充满房间
晨露和甜蜜的芬芳
鸟儿唱着它们的旋律
又是一个宁静的日子

你可以从上述 URL 下载或播放音频。

✅ 歌曲 2 生成成功！

📌 标题: 早晨的宁静
🆔 ID: d8741749-c9cb-5095-987c-7ee8f7ffb907
🔗 下载 URL: https://cdn.musicmcp.ai/songs/def456.mp3
🖼️ 封面图片: https://cdn.musicmcp.ai/images/def456.jpg
⏱️ 时长: 213 秒
🎵 风格标签: ambient, meditation, peaceful
🎹 纯乐器: 否
📅 创建时间: 2025-01-15T10:30:45.126Z
📝 歌词:
[主歌]
平静而安静，柔和而静止
山上宁静的思绪
周围是大自然的美丽
温柔的低语，舒缓的声音

你可以从上述 URL 下载或播放音频。

2. 🎵 生成自定义歌曲（自定义模式）

根据你提供的特定歌词、标题和风格参数生成 AI 音乐。

• 费用：每次生成 5 个信用点（生成 2 首歌曲）
• 参数：
  • title (str)：歌曲标题（必需）
  • instrumental (bool)：是否仅生成纯乐器音乐（必需）
  • lyric (str, 可选)：完整的歌词内容（当 instrumental 为 true 时不需要）
  • tags (str, 可选)：音乐风格标签（例如，'pop'、'rock'、'folk'）
• 示例用法：

请帮我生成一首歌曲：
标题: 夏日梦想
歌词: [完整歌词内容]
风格: 民谣

或者对于纯乐器歌曲：
标题: 夏日微风
纯乐器: 是
风格: 氛围音乐

• 输出示例：

✅ 自定义歌曲 '夏日梦想'（版本 1）生成成功！

📌 标题: 夏日梦想
🆔 ID: d1ed75a7-3e0b-42c6-b2be-7631204074fe
🔗 下载 URL: https://cdn.musicmcp.ai/songs/xyz789.mp3
🖼️ 封面图片: https://cdn.musicmcp.ai/images/xyz789.jpg
⏱️ 时长: 195 秒
🎵 风格标签: folk, acoustic, summer
🎹 纯乐器: 否
📅 创建时间: 2025-01-15T11:45:30.456Z
📝 歌词:
[主歌]
漫步在夏日的田野
金色的小麦和大自然的馈赠
阳光在我脸上舞动
夏日温暖而甜蜜的拥抱

你可以从上述 URL 下载或播放音频。

✅ 自定义歌曲 '夏日梦想'（版本 2）生成成功！

📌 标题: 夏日梦想
🆔 ID: e2fe86b8-4f1c-53d7-c3cf-8742305185gf
🔗 下载 URL: https://cdn.musicmcp.ai/songs/uvw012.mp3
🖼️ 封面图片: https://cdn.musicmcp.ai/images/uvw012.jpg
⏱️ 时长: 203 秒
🎵 风格标签: folk, acoustic, summer
🎹 纯乐器: 否
📅 创建时间: 2025-01-15T11:45:30.459Z
📝 歌词:
[主歌]
漫步在夏日的田野
金色的小麦和大自然的馈赠
阳光在我脸上舞动
夏日温暖而甜蜜的拥抱

你可以从上述 URL 下载或播放音频。

3. ✅ 检查信用余额

检查你的 API 密钥是否有效，并查看剩余的信用点。

• 费用：免费
• 示例用法：

"检查我的信用余额"
"我还剩下多少信用点？"

4. 🏥 检查 API 健康状态

监控 MusicMCP.AI API 服务的健康状态。

• 费用：免费
• 示例用法：

"检查 API 服务状态"

💰 信用点与定价

💻 使用示例

基础用法

⚠️ 重要提示

使用音乐生成工具需要 MusicMCP.AI 信用点。

你可以尝试向 Claude 提问：

灵感模式：

• "请帮我生成一首关于宁静早晨的歌曲"
• "想要一首表达思念的歌曲"
• "创作一首关于友谊的音乐"
• "生成一首氛围音乐曲目"

自定义模式：

• "请帮我生成一首歌曲，标题：夏日梦想，歌词：[完整歌词]，风格：民谣"
• "创作一首歌曲，标题：春天的承诺，歌词：[完整歌词]，流行风格"
• "生成一首纯乐器歌曲，标题：海风，风格：氛围音乐"

管理功能：

• "检查我的信用余额"
• "我还剩下多少信用点？"
• "检查 API 服务状态"

📦 安装

使用 uv（推荐）

uvx aimusic-mcp

使用 pip

pip install aimusic-mcp

🔌 API 集成

此 MCP 服务器与 MusicMCP.AI 的 RESTful API 集成：

• POST /music/generate/inspiration：创建音乐生成任务（灵感模式）
• POST /music/generate/custom：创建自定义音乐生成任务
• POST /music/generate/query：查询音乐状态（支持批量查询）
• GET /credit：检查信用余额
• GET /health：检查 API 服务健康状态

🔄 异步 API 工作流程

音乐生成是 异步的。MCP 服务器会自动处理此过程：

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

POST /music/generate/inspiration 或 /music/generate/custom
→ 返回: {"code": 200, "data": {"ids": ["id1", "id2"]}}

2. 步骤 2：自动轮询（由 MCP 内部处理）

POST /music/generate/query 并携带 {"ids": ["id1", "id2"]}
→ 每 2 秒轮询一次，直到状态 = 1（完成）
→ 歌曲状态：0 = 失败，1 = 完成，2 = 进行中

3. 步骤 3：返回完整歌曲信息

一旦所有歌曲完成，返回完整详细信息：
- 歌曲名称、歌曲 URL、图片 URL、时长、标签等。

幕后流程：

1. 用户调用 generate_prompt_song() 或 generate_custom_song()
2. MCP 发送生成请求 → 接收 2 个歌曲 ID
3. MCP 每 2 秒自动轮询 /music/generate/query
4. 当所有歌曲完成（状态 = 1）时，返回下载 URL
5. 默认超时时间：10 分钟（可通过 TIME_OUT_SECONDS 配置）

重要注意事项：

• ⏱️ 每首歌曲的生成通常需要 2 - 5 分钟
• 🔁 MCP 服务器会自动处理所有轮询
• 🎵 每次生成总是创建 2 个歌曲变体
• 💰 生成请求成功时扣除 5 个信用点
• ⚠️ 如果生成失败，不会消耗信用点

🐛 故障排除

常见问题

1. API 密钥错误：确保 MUSICMCP_API_KEY 设置正确。
   • 使用 check_credit_balance 工具检查你的密钥。
2. 信用点不足（402 错误）：你的信用点不足。
   • 在 https://www.musicmcp.ai 上检查你的余额。
   • 为你的账户充值。
3. 超时错误：如果音乐生成时间较长，请增加 TIME_OUT_SECONDS。

日志

当与 Claude Desktop 一起运行时，日志可以在以下位置找到：

• Windows：%APPDATA%\Claude\logs\mcp-server-MusicMCP.AI.log
• macOS：~/Library/Logs/Claude/mcp-server-MusicMCP.AI.log

🧪 开发

运行测试

pytest tests/

本地开发

python -m musicmcp_ai_mcp.api

代码结构

musicmcp_ai_mcp/
├── __init__.py          # 包初始化
├── __main__.py          # CLI 入口点
└── api.py               # 核心 MCP 服务器实现（430 行）

🔗 链接

• 平台：https://www.musicmcp.ai
• 文档：https://www.musicmcp.ai/docs
• 支持：support@musicmcp.ai

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。