Aimusic MCP Tool

🎵 MusicMCP.AI MCP Server

AI-Powered Music Generation via the Model Context Protocol

The official MusicMCP.AI Model Context Protocol (MCP) server enables seamless interaction with our advanced AI music generation platform. It lets MCP clients such as Claude Desktop and OpenAI Agents generate AI music through natural language commands.

✨ Features

• 🎼 AI Music Generation — Generate songs from text prompts using MusicMCP.AI's state-of-the-art models
• 🎵 Dual Generation Modes — Support for both Inspiration mode and Custom mode
• 🔗 Direct Download Links — Get direct download URLs for generated music
• 🎹 Instrumental Options — Generate instrumental-only tracks or full songs with vocals
• ✅ Credit Balance Check — Verify your API key validity and remaining credits
• 🏥 Health Monitoring — Check the API service health status

🚀 Quickstart with Claude Desktop

Step 1 — Get Your API Key Obtain your API key from the MusicMCP.AI Platform.

Step 2 — Install uv Install the Python package manager:

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

Step 3 — Configure Claude Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json and add:

{
    "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"
            }
        }
    }
}

Step 4 — Restart Claude Restart the Claude app. You'll see 4 MCP tools available, indicating successful loading. ✅

⚙️ Environment Variables

🛠️ Available Tools

1. 🎼 Generate Prompt Song (Inspiration Mode)

Generate AI music from simple text descriptions. The AI automatically creates the title, lyrics, and style.

💰 Cost: 5 credits per generation (creates 2 songs)

Parameters:

Example Prompts:

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

Output Example:

✅ 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. 🎵 Generate Custom Song (Custom Mode)

Generate AI music with specific lyrics, title, and style parameters that you provide.

💰 Cost: 5 credits per generation (creates 2 songs)

Parameters:

Example Usage:

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

Output Example:

✅ 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. ✅ Check Credit Balance

Check if your API key is valid and see your remaining credits.

💰 Cost: Free

Example Usage:

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

4. 🏥 Check API Health

Monitor the health status of the MusicMCP.AI API service.

💰 Cost: Free

Example Usage:

"Check API service status"

💰 Credits & Pricing

💡 Example Usage

⚠️ Note MusicMCP.AI credits are required to use the music generation tools.

🎼 Inspiration Mode

• "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"

🎵 Custom Mode

• "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"

📊 Management Functions

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

📦 Installation

Using uv (Recommended)

uvx aimusic-mcp

Using pip

pip install aimusic-mcp

🔌 API Integration

This MCP server integrates with MusicMCP.AI's RESTful API:

🔄 Async API Workflow

Music generation is asynchronous. The MCP server handles this automatically.

Step 1 — Submit Generation Request

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

Step 2 — Automatic Polling (handled internally by 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

Step 3 — Return Complete Song Information

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

Behind the Scenes:

1. User calls generate_prompt_song() or generate_custom_song()
2. MCP sends generation request → receives 2 song IDs
3. MCP automatically polls /music/generate/query every 2 seconds
4. When all songs complete (status=1), returns download URLs
5. Default timeout: 10 minutes (configurable via TIME_OUT_SECONDS)

⚠️ Important Notes

• ⏱️ Generation typically takes 2–5 minutes per song
• 🔁 The MCP server handles all polling automatically
• 🎵 Each generation always creates 2 song variations
• 💰 Credits (5) are deducted when the generation request succeeds
• ⚠️ If generation fails, credits are NOT consumed

🐛 Troubleshooting

Common Issues

1. API Key Error Ensure MUSICMCP_API_KEY is set correctly.

• Use the check_credit_balance tool to check your key

2. Insufficient Credits (402 Error) You don't have enough credits.

• Check your balance at https://www.musicmcp.ai
• Recharge your account

3. Timeout Errors Increase TIME_OUT_SECONDS if music generation takes longer.

📜 Logs

When running with Claude Desktop, logs can be found at:

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

🧪 Development

Running Tests

pytest tests/

Local Development

python -m musicmcp_ai_mcp.api

Code Structure

musicmcp_ai_mcp/
├── __init__.py          # Package initialization
├── __main__.py          # CLI entry point
└── api.py               # Core MCP server implementation (430 lines)

🔗 Links

• Platform: https://www.musicmcp.ai
• Documentation: https://www.musicmcp.ai/docs
• Support: support@musicmcp.ai

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.