Aimusic MCP Tool

✨ 主要特性

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

🚀 在 Claude Desktop 中快速开始

1. 获取 API Key：从 MusicMCP.AI 平台 获取你的 API key
2. 安装 uv：使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装 Python 包管理器
3. 配置 Claude：进入 Claude > Settings > Developer > Edit Config > 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"）

示例提示：

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

输出示例：

✅ Song 1 generated successfully!

📌 Title: Peaceful Morning
🆔 ID: c7630638-b8ba-4984-876b-6dd7e6eeb796
🔗 Download URL: https://cdn.musicmcp.ai/songs/abc123.mp3
🖼️  Cover Image: https://cdn.musicmcp.ai/images/abc123.jpg
⏱️  Duration: 180s
🎵 Style Tags: ambient, meditation, peaceful
🎹 Instrumental: No
📅 Created: 2025-01-15T10:30:45.123Z
📝 Lyrics:
[Verse]
Gentle sunlight fills the room
Morning dew and sweet perfume
Birds are singing their refrain
Another peaceful day again

You can download or play the audio from the URL above.

✅ Song 2 generated successfully!

📌 Title: Morning Peace
🆔 ID: d8741749-c9cb-5095-987c-7ee8f7ffb907
🔗 Download URL: https://cdn.musicmcp.ai/songs/def456.mp3
🖼️  Cover Image: https://cdn.musicmcp.ai/images/def456.jpg
⏱️  Duration: 213s
🎵 Style Tags: ambient, meditation, peaceful
🎹 Instrumental: No
📅 Created: 2025-01-15T10:30:45.126Z
📝 Lyrics:
[Verse]
Calm and quiet, soft and still
Peaceful thoughts upon the hill
Nature's beauty all around
Gentle whispers, soothing sound

You can download or play the audio from the URL above.

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

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

费用：每次生成 5 积分（生成 2 首歌曲）

参数：

• title（str）：歌曲标题（必填）
• instrumental（bool）：是否仅生成器乐音乐（必填）
• lyric（str，可选）：完整歌词内容（当 instrumental 为 true 时非必填）
• tags（str，可选）：音乐风格标签（例如 'pop'、'rock'、'folk'）

示例用法：

请帮我生成一首歌曲：
Title: Summer Dreams
Lyrics: [完整歌词内容]
Style: folk

或器乐：
Title: Summer Breeze
Instrumental: yes
Style: ambient

输出示例：

✅ Custom song 'Summer Dreams' (version 1) generated successfully!

📌 Title: Summer Dreams
🆔 ID: d1ed75a7-3e0b-42c6-b2be-7631204074fe
🔗 Download URL: https://cdn.musicmcp.ai/songs/xyz789.mp3
🖼️ Cover Image: https://cdn.musicmcp.ai/images/xyz789.jpg
⏱️ Duration: 195s
🎵 Style Tags: folk, acoustic, summer
🎹 Instrumental: No
📅 Created: 2025-01-15T11:45:30.456Z
📝 Lyrics:
[Verse]
Walking through the summer fields
Golden wheat and nature's yields
Sunshine dancing on my face
Summer's warm and sweet embrace

You can download or play the audio from the URL above.

✅ Custom song 'Summer Dreams' (version 2) generated successfully!

📌 Title: Summer Dreams
🆔 ID: e2fe86b8-4f1c-53d7-c3cf-8742305185gf
🔗 Download URL: https://cdn.musicmcp.ai/songs/uvw012.mp3
🖼️ Cover Image: https://cdn.musicmcp.ai/images/uvw012.jpg
⏱️ Duration: 203s
🎵 Style Tags: folk, acoustic, summer
🎹 Instrumental: No
📅 Created: 2025-01-15T11:45:30.459Z
📝 Lyrics:
[Verse]
Walking through the summer fields
Golden wheat and nature's yields
Sunshine dancing on my face
Summer's warm and sweet embrace

You can download or play the audio from the URL above.

3. ✅ 查询积分余额

检查 API key 是否有效并查看剩余积分。

费用：免费

示例用法：

"查询我的积分余额"
"我还剩多少积分？"

4. 🏥 检查 API 健康状态

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

费用：免费

示例用法：

"检查 API 服务状态"

💰 积分与定价

💡 示例用法

⚠️ 注意：使用音乐生成工具需要 MusicMCP.AI 积分。

尝试向 Claude 提问：

灵感模式：

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

自定义模式：

• "请帮我生成一首歌曲，标题：Summer Dreams，歌词：[完整歌词]，风格：folk"
• "创作一首歌曲，标题：Spring Promise，歌词：[完整歌词]，流行风格"
• "生成一首器乐歌曲，标题：Ocean Breeze，风格：ambient"

管理功能：

• "查询我的积分余额"
• "我还剩多少积分？"
• "检查 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 步：提交生成请求

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

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

POST /music/generate/query with {"ids": ["id1", "id2"]}
→ Polls every 2 seconds until status = 1 (completed)
→ Song status: 0 = Failed, 1 = Completed, 2 = In Progress

第 3 步：返回完整歌曲信息

Once all songs are completed, returns full details:
- songName, songUrl, imgUrl, duration, tags, etc.

幕后流程：

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

重要说明：

• ⏱️ 每首歌曲生成通常需要 2-5 分钟
• 🔁 MCP 服务器自动处理所有轮询
• 🎵 每次生成始终创建 2 个歌曲版本
• 💰 生成请求成功时扣除积分（5）
• ⚠️ 如果生成失败，不会消耗积分

🐛 故障排除

常见问题

1. API Key 错误：确保 MUSICMCP_API_KEY 设置正确

   • 使用 check_credit_balance 工具检查你的 key

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          # Package initialization
├── __main__.py          # CLI entry point
└── api.py               # Core MCP server implementation (430 lines)

🔗 链接

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

📄 许可证

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