Documentation

Complete guide to integrating and using AI Music MCP

Prefer REST API? View API Documentation

Getting Started

Set up AI Music MCP in minutes

1. Create Your Account

Visit musicmcp.ai and sign up for a free account. You'll receive trial credits to test the service.

2. Get Your API Key

Navigate to your dashboard and generate your API key. Keep this key secure - you'll need it for authentication.

3. Choose Your Integration Method

Select how you want to use AI Music MCP based on your needs.

Integration Methods

Choose the best method for your use case

Claude Desktop

For individual users and quick prototyping

1

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

2

Locate your Claude Desktop config file: • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json • Windows: %APPDATA%\Claude\claude_desktop_config.json

3

Add the MCP server configuration

4

Restart Claude Desktop

5

Verify 5 MCP tools are available in Claude

claude_desktop_config.json
1{
2  "mcpServers": {
3    "MusicMCP.AI": {
4      "command": "uvx",
5      "args": ["aimusic-mcp"],
6      "env": {
7        "MUSICMCP_API_KEY": "<your-api-key>",
8        "MUSICMCP_API_URL": "https://www.musicmcp.ai/api",
9        "TIME_OUT_SECONDS": "600"
10      }
11    }
12  }
13}

Custom Agent / Application

For developers building AI applications

1

Install the package: pip install aimusic-mcp

2

Import and initialize in your code

3

Call the 5 available MCP tools through the protocol

4

Handle responses and download URLs

example.py
1from musicmcp_ai_mcp import MusicMCPClient
2
3# Initialize client
4client = MusicMCPClient(
5    api_key="your-api-key",
6    api_url="https://www.musicmcp.ai/api"
7)
8
9# Generate music
10result = await client.generate_prompt_song(
11    prompt="peaceful morning song",
12    instrumental=False
13)

How to Use

Generate music with simple commands

Inspiration Mode

Generate music from simple text descriptions

Examples:

"Generate a peaceful morning song"
"Create upbeat electronic music for a workout"
"Make ambient music for meditation"

Tip: Describe the mood, scene, or feeling you want. The AI handles title, lyrics, and arrangement.

Custom Mode

Full control with your own lyrics and style

Examples:

"Create a song titled 'Summer Dreams' with folk style"
"Generate pop music with these lyrics: [your lyrics]"
"Make a rock ballad called 'Memories' with my lyrics"

Tip: Provide title, complete lyrics, and style tags for precise control.

Instrumental Mode

Generate music without vocals

Examples:

"Create instrumental jazz for background"
"Generate cinematic orchestral music"
"Make lo-fi beats without lyrics"

Tip: Perfect for background music, games, and content creation.

Available Tools

4 MCP tools at your disposal

generate_prompt_song5 credits → 2 songs

Generate music from text prompts (Inspiration Mode)

generate_custom_song5 credits → 2 songs

Generate songs with custom lyrics and style

check_credit_balanceFree

Check your API key and remaining credits

check_api_healthFree

Monitor API service status

Output Fields

Complete song information returned after generation

When music generation completes, you receive rich metadata for each song:

📌

Title

Generated song title (or your custom title)

🆔

ID

Unique identifier for the song

🔗

Download URL

Direct MP3 download link (full-length, 4+ minutes)

🖼️

Cover Image

AI-generated cover art URL

⏱️

Duration

Song length in seconds

🎵

Style Tags

Music genre and style labels

🎹

Instrumental

Whether the song is instrumental (Yes/No)

📅

Created

Timestamp when the song was generated

📝

Lyrics

Complete song lyrics (for non-instrumental songs)

💡 The MCP server automatically polls the API and returns complete information once generation is finished. You don't need to manually query for status.

Troubleshooting

Common issues and solutions

❌ API Key Error

✓ Solution: Ensure MUSICMCP_API_KEY is correctly set in your environment variables. Use check_credit_balance to verify.

❌ Insufficient Credits (402 Error)

✓ Solution: You've run out of credits. Check your balance and purchase more credits from the dashboard.

❌ Timeout Errors

✓ Solution: Increase TIME_OUT_SECONDS in your configuration. Default is 600 (10 minutes).

❌ MCP Tools Not Showing

✓ Solution: Restart your MCP client (Claude Desktop). Verify the configuration file is valid JSON.

❌ Generation Failed

✓ Solution: Check API health status. If service is operational, verify your prompt follows guidelines.