Skip to main content
Glama
fastmcp-me

MusicMCP.AI MCP Server

by fastmcp-me
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Remote

Add to Cursor Add to VS Code Add to Claude Add to ChatGPT Add to Codex Add to Gemini

🎵 MusicMCP.AI MCP Server

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

Related MCP server: Suno MCP

🚀 Quickstart with Claude Desktop

  1. Get Your API Key: Obtain your API key from MusicMCP.AI Platform

  2. Install uv: Install the Python package manager with curl -LsSf https://astral.sh/uv/install.sh | sh

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

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

⚙️ Environment Variables

Variable

Description

Default

Required

MUSICMCP_API_KEY

Your MusicMCP.AI API key

-

✅ Yes

MUSICMCP_API_URL

MusicMCP.AI API base URL

https://www.musicmcp.ai/api

❌ No

TIME_OUT_SECONDS

Timeout for music generation in seconds

600 (10 min)

❌ No

🛠️ 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:

✅ 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:

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

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

Operation

Credits Cost

Output

Generate Inspiration Music

5 credits

2 songs

Generate Custom Music

5 credits

2 songs

Query Music Status

0 credits (Free)

-

Check Credit Balance

0 credits (Free)

-

API Health Check

0 credits (Free)

-

💡 Example Usage

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

Try asking Claude:

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:

  • 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

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

  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

📄 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

Available Tools

4 tools
check_api_healthA

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
typeYes
textYes
annotationsNo
_metaNo

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. The description only states a health check, omitting any indication of side effects, rate limits, or idempotence, which is insufficient for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence front-loading the purpose, zero wasted words, perfectly concise for a no-parameter health check.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple no-parameter health check, the description is complete. An output schema exists to handle return value details, so no further explanation is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100%. The description adds no parameter info, but baseline score for 0 parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'check' and resource 'health status of the MusicMCP.AI API service', distinguishing it from sibling tools like check_credit_balance and song generation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. Usage is implied as checking API health, but no exclusions or alternative suggestions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_credit_balanceB

Check your credit balance.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
typeYes
textYes
annotationsNo
_metaNo

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description only implies a read-only operation but provides no additional behavioral details such as side effects, rate limits, or authentication requirements. With no annotations available, the description carries the full burden and is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence with no unnecessary words. It is front-loaded and efficiently conveys the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a zero-parameter tool, but it does not clarify what 'credit balance' refers to. Although an output schema exists, the description could provide more context about the credit system. It is minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the baseline is 4. The description adds no extra meaning beyond the schema, but that is acceptable given the schema coverage is 100%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action (check) and resource (credit balance), and it is distinct from sibling tools like check_api_health or generate_custom_song. However, it lacks specificity about which credit system is being checked.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. While sibling tools are different in functionality, the description does not mention any context or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_custom_songA

🎵 Custom Mode: Generate songs based on detailed song information (user specifies song name, lyrics, style, etc.)

Use case: Use when users provide detailed song information including song name, complete lyrics, and style.

Example inputs:
- "Song name: Summer of Cicada Shedding, Lyrics: [complete lyrics], style: folk"

⚠️ COST WARNING: This tool makes an API call to MusicMCP.AI which may incur costs (5 credits per generation). Each generation creates 2 songs. Only use when explicitly requested by the user.

Language Note: Pass the title and lyrics in the user's input language.

Args:
    title (str): Song title, required
    lyric (str, optional): Complete lyrics content, not required when instrumental is True
    tags (str, optional): Music style tags (e.g., 'pop', 'rock', 'folk')
    instrumental (bool): Whether instrumental only (no lyrics)

Returns:
    Song information including download URLs
ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes
instrumentalYes
lyricNo
tagsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses API call, cost (5 credits), creates 2 songs, and language note. No annotations provided, so description carries full burden and does it well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections, front-loaded purpose. Slightly lengthy but every sentence adds value. Could be more concise but still effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers inputs, cost, language, and output (download URLs). Output schema exists but description provides additional context. Complete enough for usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but description adds meaning: explains each param, optionality, condition (lyric not required if instrumental). Good compensation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it generates songs based on detailed information, with examples. Distinguishes from sibling 'generate_prompt_song' by emphasizing detailed song info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides when-to-use guidance (user provides detailed info), cost warning, and explicit condition 'Only use when explicitly requested'. Does not contrast with sibling tool though.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_prompt_songA

🎼 Inspiration Mode: Generate songs based on simple text descriptions (AI automatically generates title, lyrics, style, etc.)

Use case: Use when users only provide simple song themes or emotional descriptions without detailed specifications.

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

⚠️ COST WARNING: This tool makes an API call to MusicMCP.AI which may incur costs (5 credits per generation). Each generation creates 2 songs. Only use when explicitly requested by the user.

Language Note: Pass the prompt in the user's input language.

Args:
    prompt (str): Song theme or emotional description, 1-1200 characters
    instrumental (bool): Whether instrumental only (no lyrics)
    style (str, optional): Music style (e.g., "ambient", "pop", "rock"), default None

Returns:
    Song information including download URLs
ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
instrumentalYes
styleNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses API call cost (5 credits, generates 2 songs), language handling, and that it is a generation tool. No annotations provided, so description carries full burden; it adequately covers behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with emoji headers, use cases, examples, and warnings. Each sentence adds value; slightly long but appropriate for complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all important aspects: purpose, usage, parameters, cost, language, example inputs. Output schema exists so return details are not needed. Complete for a generation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but description compensates by explaining each parameter: prompt character limit, instrumental as boolean, style with examples. Adds meaning beyond schema structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool generates songs from simple text descriptions, automatically handling title, lyrics, style. Distinguishes from sibling 'generate_custom_song' through 'Inspiration Mode' and example inputs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states use case: when users provide simple themes without detailed specs. Includes cost warning and language note, guiding appropriate usage. Does not explicitly mention alternatives but context implies when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.6
    • First observedcheck_api_health
    • First observedcheck_credit_balance
    • First observedgenerate_custom_song
    • First observedgenerate_prompt_song
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: health check, credit check, custom song generation, and prompt-based generation. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (check_api_health, check_credit_balance, generate_custom_song, generate_prompt_song), making it easy to predict functionality.

Tool Count5/5

With 4 tools, the server is well-scoped for its purpose: two generation modes plus essential support tools (health and credit). Not too few or too many.

Completeness3/5

The domain is music generation, but missing features like listing past generations, checking generation status, or deleting songs. Users can generate but not manage results.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers