MusicGPT MCP Server

# MusicGPT MCP Server A Model Context Protocol (MCP) server for the [MusicGPT API](https://musicgpt.com/), 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 ```bash npm install mcp-server-musicgpt ``` Or install from source: ```bash 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](https://musicgpt.com/api-dashboard) 2. Sign up for an account 3. Generate your API key ### Environment Variables Set the following environment variable: ```bash export MUSICGPT_API_KEY="your_api_key_here" ``` Optional configuration: ```bash 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`: ```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 ```json { "mcpServers": { "musicgpt": { "command": "node", "args": ["/path/to/mcp-server-musicgpt/dist/index.js"], "env": { "MUSICGPT_API_KEY": "your_api_key_here" } } } } ``` #### Windows ```json { "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: ```json { "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. ```typescript { "conversionType": "MUSIC_AI", "task_id": "uuid-here" // or use conversion_id } ``` #### `get_all_voices` List all available voices with pagination. ```typescript { "limit": 20, // optional, default: 20 "page": 0 // optional, default: 0 } ``` #### `search_voices` Search for voices by name. ```typescript { "voice_name": "Taylor Swift" } ``` ### Music Generation Tools #### `generate_music` Generate custom music from a text prompt. ```typescript { "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. ```typescript { "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. ```typescript { "prompt": "Thunder and rain in a forest", "duration": 5 // optional, in seconds } ``` #### `generate_lyrics` Generate song lyrics from a theme or prompt. ```typescript { "prompt": "A song about summer adventures", "genre": "Pop" // optional } ``` ### Voice & Speech Tools #### `voice_changer` Convert audio to a different voice. ```typescript { "audio_url": "https://example.com/audio.mp3", "voice_id": "voice-uuid" } ``` #### `text_to_speech` Convert text to speech. ```typescript { "text": "Hello, this is a text-to-speech conversion", "voice_id": "voice-uuid" } ``` ### Audio Processing Tools #### `extract_audio` Extract vocals, instruments, or stems. ```typescript { "audio_url": "https://example.com/song.mp3", "extraction_type": "vocals" // vocals, instrumental, drums, bass, piano, other } ``` #### `denoise_audio` Remove background noise from audio. ```typescript { "audio_url": "https://example.com/noisy-audio.mp3" } ``` #### `deecho_audio` Remove echo from audio. ```typescript { "audio_url": "https://example.com/audio-with-echo.mp3" } ``` #### `dereverb_audio` Remove reverb from audio. ```typescript { "audio_url": "https://example.com/audio-with-reverb.mp3" } ``` ### Audio Manipulation Tools #### `convert_audio_format` Convert audio to different formats. ```typescript { "audio_url": "https://example.com/audio.wav", "output_format": "mp3" // mp3, wav, flac, ogg, m4a } ``` #### `cut_audio` Trim audio to specific time range. ```typescript { "audio_url": "https://example.com/audio.mp3", "start_time": 10, // seconds "end_time": 60 // seconds } ``` #### `change_audio_speed` Change playback speed. ```typescript { "audio_url": "https://example.com/audio.mp3", "speed_factor": 1.5 // 1.5x speed } ``` #### `master_audio` Apply professional audio mastering. ```typescript { "audio_url": "https://example.com/unmastered.mp3" } ``` #### `remix_audio` Create a remix of audio. ```typescript { "audio_url": "https://example.com/song.mp3", "remix_style": "House" // optional } ``` #### `extend_audio` Extend audio using AI continuation. ```typescript { "audio_url": "https://example.com/song.mp3", "extension_duration": 30 // seconds, optional } ``` #### `inpaint_audio` Fill gaps or corrupted sections in audio. ```typescript { "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. ```typescript { "instrumental_url": "https://example.com/instrumental.mp3", "lyrics": "Verse 1: ...", "voice_id": "voice-uuid" } ``` ### Analysis Tools #### `transcribe_audio` Transcribe speech to text. ```typescript { "audio_url": "https://example.com/speech.mp3", "language": "en" // optional, e.g., en, es, fr } ``` #### `extract_key_bpm` Extract musical key and BPM. ```typescript { "audio_url": "https://example.com/song.mp3" } ``` #### `audio_to_midi` Convert audio to MIDI format. ```typescript { "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: ```typescript // 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: ```typescript { "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](https://docs.musicgpt.com/) - [API Dashboard](https://musicgpt.com/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](https://musicgpt.com/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: ```bash npm run build ``` Development mode (watch for changes): ```bash npm run dev ``` ## Credits & Costs Most operations consume API credits. Check the [pricing page](https://docs.musicgpt.com/api-documentation/index/pricing) for details. ## License MIT ## Support For issues with this MCP server: - [Create an issue](https://github.com/pasie15/mcp-server-musicgpt/issues) For MusicGPT API issues: - [MusicGPT Support](https://musicgpt.com/api-dashboard) - [API Documentation](https://docs.musicgpt.com/) ## Links - [MusicGPT Website](https://musicgpt.com/) - [API Documentation](https://docs.musicgpt.com/) - [API Dashboard](https://musicgpt.com/api-dashboard) - [Model Context Protocol](https://modelcontextprotocol.io/)