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