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 文件。