MusicGPT MCP Server

A Model Context Protocol (MCP) server for the MusicGPT API, providing AI-powered audio generation and processing capabilities.

Features

Music Generation

• Generate Music: Create custom music from text prompts with optional lyrics
• Cover Songs: Create cover versions with different voices
• Sound Effects: Generate sound effects from descriptions
• Lyrics Generation: Generate song lyrics based on themes

Voice & Speech

• Voice Changer: Convert audio to different AI voices
• Text-to-Speech: Convert text to natural-sounding speech
• Voice Library: Access 3000+ AI voices

Audio Processing

• Audio Extraction: Isolate vocals, instruments, or specific stems
• Denoise/Deecho/Dereverb: Clean up audio recordings
• Audio Mastering: Professional-quality audio mastering
• Format Conversion: Convert between audio formats

Audio Manipulation

• Audio Cutter: Trim audio to specific durations
• Speed Changer: Adjust playback speed
• Remix: Create remixes of tracks
• Extend: AI-powered audio extension
• Inpaint: Fill gaps in audio
• Sing Over Instrumental: Add AI vocals to instrumentals

Analysis Tools

• Transcription: Convert speech to text
• Key & BPM Detection: Extract musical key and tempo
• Audio to MIDI: Convert audio to MIDI format

Installation

npm install mcp-server-musicgpt

Or install from source:

git clone https://github.com/pasie15/mcp-server-musicgpt.git
cd mcp-server-musicgpt
npm install
npm run build

Configuration

Get Your API Key

1. Visit MusicGPT API Dashboard
2. Sign up for an account
3. Generate your API key

Environment Variables

Set the following environment variable:

export MUSICGPT_API_KEY="your_api_key_here"

Optional configuration:

export MUSICGPT_BASE_URL="https://api.musicgpt.com/api/public/v1"  # Default
export MUSICGPT_TIMEOUT="60000"  # Timeout in milliseconds (default: 60000)

Usage with MCP Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "musicgpt": {
      "command": "npx",
      "args": ["-y", "mcp-server-musicgpt"],
      "env": {
        "MUSICGPT_API_KEY": "your_api_key_here"
      }
    }
  }
}

<details> <summary>Alternative: Install from source</summary>

MacOS/Linux

{
  "mcpServers": {
    "musicgpt": {
      "command": "node",
      "args": ["/path/to/mcp-server-musicgpt/dist/index.js"],
      "env": {
        "MUSICGPT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "musicgpt": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-server-musicgpt\\dist\\index.js"],
      "env": {
        "MUSICGPT_API_KEY": "your_api_key_here"
      }
    }
  }
}

</details>

Cline

Add to your MCP settings:

{
  "musicgpt": {
    "command": "npx",
    "args": ["-y", "mcp-server-musicgpt"],
    "env": {
      "MUSICGPT_API_KEY": "your_api_key_here"
    }
  }
}

Available Tools

Helper Tools

get_conversion_by_id

Get the status and results of a conversion task.

{
  "conversionType": "MUSIC_AI",
  "task_id": "uuid-here"  // or use conversion_id
}

get_all_voices

List all available voices with pagination.

{
  "limit": 20,  // optional, default: 20
  "page": 0     // optional, default: 0
}

search_voices

Search for voices by name.

{
  "voice_name": "Taylor Swift"
}

Music Generation Tools

generate_music

Generate custom music from a text prompt.

{
  "prompt": "An upbeat electronic dance track with energetic synths",
  "music_style": "EDM",  // optional
  "lyrics": "Verse 1: ...",  // optional
  "make_instrumental": false,  // optional
  "vocal_only": false,  // optional
  "voice_id": "voice-uuid",  // optional
  "webhook_url": "https://example.com/webhook"  // optional
}

create_cover_song

Create a cover version with a different voice.

{
  "audio_url": "https://example.com/song.mp3",
  "voice_id": "voice-uuid",
  "webhook_url": "https://example.com/webhook"  // optional
}

generate_sound_effect

Generate sound effects from text descriptions.

{
  "prompt": "Thunder and rain in a forest",
  "duration": 5  // optional, in seconds
}

generate_lyrics

Generate song lyrics from a theme or prompt.

{
  "prompt": "A song about summer adventures",
  "genre": "Pop"  // optional
}

Voice & Speech Tools

voice_changer

Convert audio to a different voice.

{
  "audio_url": "https://example.com/audio.mp3",
  "voice_id": "voice-uuid"
}

text_to_speech

Convert text to speech.

{
  "text": "Hello, this is a text-to-speech conversion",
  "voice_id": "voice-uuid"
}

Audio Processing Tools

extract_audio

Extract vocals, instruments, or stems.

{
  "audio_url": "https://example.com/song.mp3",
  "extraction_type": "vocals"  // vocals, instrumental, drums, bass, piano, other
}

denoise_audio

Remove background noise from audio.

{
  "audio_url": "https://example.com/noisy-audio.mp3"
}

deecho_audio

Remove echo from audio.

{
  "audio_url": "https://example.com/audio-with-echo.mp3"
}

dereverb_audio

Remove reverb from audio.

{
  "audio_url": "https://example.com/audio-with-reverb.mp3"
}

Audio Manipulation Tools

convert_audio_format

Convert audio to different formats.

{
  "audio_url": "https://example.com/audio.wav",
  "output_format": "mp3"  // mp3, wav, flac, ogg, m4a
}

cut_audio

Trim audio to specific time range.

{
  "audio_url": "https://example.com/audio.mp3",
  "start_time": 10,  // seconds
  "end_time": 60     // seconds
}

change_audio_speed

Change playback speed.

{
  "audio_url": "https://example.com/audio.mp3",
  "speed_factor": 1.5  // 1.5x speed
}

master_audio

Apply professional audio mastering.

{
  "audio_url": "https://example.com/unmastered.mp3"
}

remix_audio

Create a remix of audio.

{
  "audio_url": "https://example.com/song.mp3",
  "remix_style": "House"  // optional
}

extend_audio

Extend audio using AI continuation.

{
  "audio_url": "https://example.com/song.mp3",
  "extension_duration": 30  // seconds, optional
}

inpaint_audio

Fill gaps or corrupted sections in audio.

{
  "audio_url": "https://example.com/audio-with-gap.mp3",
  "start_time": 10,  // gap start in seconds
  "end_time": 15     // gap end in seconds
}

sing_over_instrumental

Add AI vocals to an instrumental track.

{
  "instrumental_url": "https://example.com/instrumental.mp3",
  "lyrics": "Verse 1: ...",
  "voice_id": "voice-uuid"
}

Analysis Tools

transcribe_audio

Transcribe speech to text.

{
  "audio_url": "https://example.com/speech.mp3",
  "language": "en"  // optional, e.g., en, es, fr
}

extract_key_bpm

Extract musical key and BPM.

{
  "audio_url": "https://example.com/song.mp3"
}

audio_to_midi

Convert audio to MIDI format.

{
  "audio_url": "https://example.com/melody.mp3"
}

Workflow Example

Most audio processing operations are asynchronous. Here's a typical workflow:

1. Start a conversion (e.g., generate_music)

   • Returns: task_id and conversion_id

2. Check status using get_conversion_by_id

   • Pass the task_id or conversion_id
   • Status values: PENDING, PROCESSING, COMPLETED, FAILED

3. Get results when status is COMPLETED

   • The response includes audio_url with the processed audio

Example:

// Step 1: Generate music
{
  "tool": "generate_music",
  "arguments": {
    "prompt": "A relaxing piano melody"
  }
}
// Returns: { task_id: "abc-123", conversion_id: "def-456", eta: 120 }

// Step 2: Check status (wait for ETA or use webhook)
{
  "tool": "get_conversion_by_id",
  "arguments": {
    "conversionType": "MUSIC_AI",
    "task_id": "abc-123"
  }
}
// Returns: { status: "COMPLETED", audio_url: "https://..." }

Webhook Support

Most conversion tools support webhooks for async notifications. Set the webhook_url parameter to receive a callback when processing completes:

{
  "prompt": "Epic orchestral music",
  "webhook_url": "https://your-server.com/musicgpt-webhook"
}

The webhook will receive a POST request with the conversion results.

API Documentation

For detailed API documentation, visit:

• MusicGPT API Documentation
• API Dashboard

Conversion Types

When using get_conversion_by_id, use these conversion types:

• MUSIC_AI - Music generation
• TEXT_TO_SPEECH - Text to speech
• VOICE_CONVERSION - Voice changer
• EXTRACTION - Audio extraction
• COVER - Cover songs
• STEMS_SEPARATION - Stems separation
• VOCAL_EXTRACTION - Vocal extraction
• DENOISING - Denoise
• DEECHO - Deecho
• DEREVERB - Dereverb
• SOUND_GENERATOR - Sound effects
• AUDIO_TRANSCRIPTION - Transcription
• AUDIO_SPEED_CHANGER - Speed changer
• AUDIO_MASTERING - Mastering
• AUDIO_CUTTER - Audio cutter
• REMIX - Remix
• FILE_CONVERT - Format conversion
• KEY_BPM_EXTRACTION - Key & BPM extraction
• AUDIO_TO_MIDI - Audio to MIDI
• EXTEND - Audio extension
• INPAINT - Audio inpainting
• SING_OVER_INSTRUMENTAL - Sing over instrumental
• LYRICS_GENERATOR - Lyrics generation

Rate Limits

MusicGPT API has rate limits based on your subscription tier. Check your API dashboard for your limits.

Troubleshooting

"Authentication failed"

• Verify your MUSICGPT_API_KEY is correct
• Check your API key is active in the dashboard
• Ensure you have sufficient credits

"Rate limit exceeded"

• Wait before making more requests
• Check your API usage in the dashboard
• Upgrade your plan if needed

Timeout errors

• Increase MUSICGPT_TIMEOUT for large audio files
• Default is 60 seconds, increase if needed

Tool not found

• Ensure the server is running
• Rebuild the project: npm run build
• Check your MCP client configuration

Development

Build the server:

npm run build

Development mode (watch for changes):

npm run dev

Credits & Costs

Most operations consume API credits. Check the pricing page for details.

License

MIT

Support

For issues with this MCP server:

• Create an issue

For MusicGPT API issues:

• MusicGPT Support
• API Documentation

Links

• MusicGPT Website
• API Documentation
• API Dashboard
• Model Context Protocol