AI-Powered Music Generation with Model Context Protocol

Official MusicMCP.AI Model Context Protocol (MCP) server that enables seamless interaction with our advanced AI music generation platform. This server allows MCP clients like Claude Desktop, OpenAI Agents and others to generate AI music through natural language commands.

✨ Features

• 🎼 AI Music Generation: Generate songs based on text prompts using MusicMCP.AI's state-of-the-art AI 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 music or full songs with vocals

• ✅ Credit Balance Check: Check your API key validity and remaining credits

• 🏥 Health Monitoring: Check API service health status

🚀 Quickstart with Claude Desktop

1. Get Your API Key

Obtain your API key from MusicMCP.AI Platform.

2. Install uv

3. Configure Claude

Go to Claude > Settings > Developer > Edit Config > and add:

4. Restart Claude

Restart the Claude app and you'll see 4 MCP tools available, indicating successful loading.

⚙️ Environment Variables

🛠️ Available Tools

1. 🎼 Generate Prompt Song (Inspiration Mode)

Generate AI music based on simple text descriptions. AI automatically creates title, lyrics, and style.

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

Parameters:

• prompt (str): Simple description of the music theme (1–1200 characters)

• instrumental (bool): Whether to generate instrumental music only

• style (str, optional): Music style (e.g., "ambient", "pop", "rock")

Example prompts:

• Help me generate a song about a peaceful morning

• Want a song that expresses longing

• Create music about friendship

Output example:

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:

• title (str): Song title (required)

• instrumental (bool): Whether to generate instrumental music only (required)

• lyric (str, optional): Complete lyrics content (not required when instrumental is true)

• tags (str, optional): Music style tags (e.g., "pop", "rock", "folk")

Example usage:

Or for instrumental:

Output example:

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)

Using pip

🔌 API Integration

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

• POST /music/generate/inspiration: Create music generation task (inspiration mode)

• POST /music/generate/custom: Create custom music generation task

• POST /music/generate/query: Query music status (batch query supported)

• GET /credit: Check credit balance

• GET /health: Check API service health

🔄 Async API Workflow

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

Step 1: Submit Generation Request

Call:

• POST /music/generate/inspiration

• or POST /music/generate/custom

Response example:

Step 2: Automatic Polling (handled internally by MCP)

MCP calls:

• Polls every 2 seconds until status = 1 (completed)

• Song status:

  • 0 = Failed

  • 1 = Completed

  • 2 = In Progress

Step 3: Return Complete Song Information

When all songs complete, the MCP server 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), MCP returns download URLs and metadata

Defaults & behavior:

• ⏱️ Generation typically takes 2–5 minutes per song

• 🔁 MCP handles polling automatically

• 🎵 Each generation always creates 2 song variations

• 💰 Credits (5) are deducted when 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 verify.

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

Local Development

Code Structure

🔗 Links

• Platform: https://www.musicmcp.ai

• Documentation: https://www.musicmcp.ai/docs

• Support: mailto:support@musicmcp.ai

📄 License

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

Made with ❤️ by the MusicMCP.AI Team

Transform your ideas into music with AI.