Aimusic MCP Tool

🚀 🎵 MusicMCP.AI MCP Server

このサーバーは、AIによる高度な音楽生成プラットフォームであるMusicMCP.AIとのシームレスなやり取りを可能にする公式のModel Context Protocol (MCP) サーバーです。これにより、Claude DesktopやOpenAI AgentsなどのMCPクライアントが自然言語コマンドを使ってAI音楽を生成できます。

✨ 主な機能

• 🎼 AI音楽生成：MusicMCP.AIの最先端のAIモデルを使って、テキストプロンプトに基づいて曲を生成します。
• 🎵 2種類の生成モード：インスピレーションモードとカスタムモードの両方をサポートしています。
• 🔗 直接ダウンロードリンク：生成された音楽の直接ダウンロードURLを取得できます。
• 🎹 楽器演奏のオプション：楽器演奏のみの音楽や、ボーカル付きの完全な曲を生成できます。
• ✅ クレジット残高確認：APIキーの有効性と残りのクレジットを確認できます。
• 🏥 ヘルスモニタリング：APIサービスのヘルスステータスを確認できます。

🚀 クイックスタート (Claude Desktopを使用する場合)

1. APIキーの取得：MusicMCP.AI Platformから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")

プロンプトの例：

"Help me generate a song about a peaceful morning"
"Want a song that expresses longing"
"Create music about friendship"

出力例：

✅ 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')

使用例：

Please help me generate a song:
Title: Summer Dreams
Lyrics: [complete lyrics content]
Style: folk

Or for instrumental:
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キーが有効かどうかを確認し、残りのクレジットを確認します。

コスト：無料

使用例：

"Check my credit balance"
"How many credits do I have left?"

4. 🏥 APIのヘルスチェック

MusicMCP.AI APIサービスのヘルスステータスを監視します。

コスト：無料

使用例：

"Check API service status"

💰 クレジットと価格

💡 使用例

⚠️ 重要な注意

音楽生成ツールを使用するには、MusicMCP.AIのクレジットが必要です。

Claudeに質問する例

インスピレーションモード：

• "Please help me generate a song about a peaceful morning"
• "Want a song that expresses longing"
• "Create music about friendship"
• "Generate an ambient music track"

カスタムモード：

• "Please help me generate a song, Title: Summer Dreams, Lyrics: [complete lyrics], Style: folk"
• "Create a song, Title Spring Promise, Lyrics: [complete lyrics], Pop style"
• "Generate an instrumental song, Title: Ocean Breeze, Style: ambient"

管理機能：

• "Check my credit balance"
• "How many credits do I have left?"
• "Check API service status"

📦 インストール

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: 完全な曲情報の返却

すべての曲が生成されると、以下の詳細情報が返されます。
- songName, songUrl, imgUrl, duration, tagsなど

内部の動作：

1. ユーザーが generate_prompt_song() または generate_custom_song() を呼び出します。
2. MCPが生成リクエストを送信し、2つの曲のIDを受け取ります。
3. MCPが自動的に /music/generate/query を2秒ごとにポーリングします。
4. すべての曲が生成されると (status = 1)、ダウンロードURLが返されます。
5. デフォルトのタイムアウト時間は10分です (TIME_OUT_SECONDS で設定可能)。

🐛 トラブルシューティング

一般的な問題

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 ファイルを参照してください。