AI MUSIC MCP

✨ Características

• 🎼 Generación de Música con IA: Genera canciones basadas en indicaciones de texto utilizando los modelos de IA de última generación de MusicMCP.AI
• 🎵 Modos Duales de Generación: Soporte tanto para el modo inspiración como para el modo personalizado
• 🔗 Enlaces de Descarga Directa: Obtén URLs de descarga directa para la música generada
• 🎹 Opciones Instrumentales: Genera música solo instrumental o canciones completas con voces
• ✅ Verificación de Saldo de Créditos: Comprueba la validez de tu clave API y los créditos restantes
• 🏥 Monitoreo de Salud: Comprueba el estado de salud del servicio API

🚀 Inicio Rápido con Claude Desktop

1. Obtén tu Clave API: Consigue tu clave API en Plataforma MusicMCP.AI
2. Instala uv: Instala el gestor de paquetes de Python con curl -LsSf https://astral.sh/uv/install.sh | sh
3. Configura Claude: Ve a Claude > Configuración > Desarrollador > Editar Configuración > claude_desktop_config.json y añade:

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

4. Reinicia Claude: Reinicia la aplicación de Claude y verás 4 herramientas MCP disponibles, lo que indica que se cargó correctamente

⚙️ Variables de Entorno

Variable	Descripción	Predeterminado	Requerido
MUSICMCP_API_KEY	Tu clave API de MusicMCP.AI	-	✅ Sí
MUSICMCP_API_URL	URL base de la API de MusicMCP.AI	https://www.musicmcp.ai/api	❌ No
TIME_OUT_SECONDS	Tiempo de espera para la generación de música en segundos	600 (10 min)	❌ No

🛠️ Herramientas Disponibles

1. 🎼 Generar Canción por Indicación (Modo Inspiración)

Genera música con IA basada en descripciones de texto simples. La IA crea automáticamente el título, la letra y el estilo.

Costo: 5 créditos por generación (crea 2 canciones)

Parámetros:

• prompt (str): Descripción simple del tema musical (1-1200 caracteres)
• instrumental (bool): Si se debe generar solo música instrumental
• style (str, opcional): Estilo musical (p. ej., "ambient", "pop", "rock")

Ejemplos de Indicaciones:

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

Ejemplo de Salida:

✅ 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. 🎵 Generar Canción Personalizada (Modo Personalizado)

Genera música con IA con letras, título y parámetros de estilo específicos que tú proporcionas.

Costo: 5 créditos por generación (crea 2 canciones)

Parámetros:

• title (str): Título de la canción (requerido)
• instrumental (bool): Si se debe generar solo música instrumental (requerido)
• lyric (str, opcional): Contenido completo de la letra (no requerido cuando instrumental es verdadero)
• tags (str, opcional): Etiquetas de estilo musical (p. ej., 'pop', 'rock', 'folk')

Ejemplo de Uso:

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

Ejemplo de Salida:

✅ 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. ✅ Verificar Saldo de Créditos

Comprueba si tu clave API es válida y consulta tus créditos restantes.

Costo: Gratis

Ejemplo de Uso:

"Check my credit balance"
"How many credits do I have left?"

4. 🏥 Verificar Salud de la API

Monitorea el estado de salud del servicio API de MusicMCP.AI.

Costo: Gratis

Ejemplo de Uso:

"Check API service status"

💰 Créditos y Precios

Operación	Costo en Créditos	Salida
Generar Música por Inspiración	5 créditos	2 canciones
Generar Música Personalizada	5 créditos	2 canciones
Consultar Estado de la Música	0 créditos (Gratis)	-
Verificar Saldo de Créditos	0 créditos (Gratis)	-
Verificación de Salud de la API	0 créditos (Gratis)	-

💡 Ejemplo de Uso

⚠️ Nota: Se requieren créditos de MusicMCP.AI para usar las herramientas de generación de música.

Prueba preguntando a Claude:

Modo Inspiración:

• "Por favor, ayúdame a generar una canción sobre una mañana tranquila"
• "Quiero una canción que exprese anhelo"
• "Crea música sobre la amistad"
• "Genera una pista de música ambiental"

Modo Personalizado:

• "Por favor, ayúdame a generar una canción, Título: Sueños de Verano, Letra: [letra completa], Estilo: folk"
• "Crea una canción, Título: Promesa de Primavera, Letra: [letra completa], Estilo pop"
• "Genera una canción instrumental, Título: Brisa del Océano, Estilo: ambient"

Funciones de Gestión:

• "Verifica mi saldo de créditos"
• "¿Cuántos créditos me quedan?"
• "Verifica el estado del servicio API"

📦 Instalación

Usando uv (Recomendado)

uvx aimusic-mcp

Usando pip

pip install aimusic-mcp

🔌 Integración de API

Este servidor MCP se integra con la API RESTful de MusicMCP.AI:

• POST /music/generate/inspiration: Crear tarea de generación de música (modo inspiración)
• POST /music/generate/custom: Crear tarea de generación de música personalizada
• POST /music/generate/query: Consultar estado de la música (soporta consulta por lotes)
• GET /credit: Verificar saldo de créditos
• GET /health: Verificar salud del servicio API

🔄 Flujo de Trabajo de API Asíncrona

La generación de música es asíncrona. El servidor MCP maneja esto automáticamente:

Paso 1: Enviar Solicitud de Generación

POST /music/generate/inspiration or /music/generate/custom
→ Returns: {"code": 200, "data": {"ids": ["id1", "id2"]}}

Paso 2: Sondeo Automático (manejado internamente por 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

Paso 3: Devolver Información Completa de la Canción

Once all songs are completed, returns full details:
- songName, songUrl, imgUrl, duration, tags, etc.

Detrás de Escena:

1. El usuario llama a generate_prompt_song() o generate_custom_song()
2. MCP envía la solicitud de generación → recibe 2 IDs de canciones
3. MCP sondea automáticamente /music/generate/query cada 2 segundos
4. Cuando todas las canciones se completan (estado=1), devuelve las URLs de descarga
5. Tiempo de espera predeterminado: 10 minutos (configurable mediante TIME_OUT_SECONDS)

Notas Importantes:

• ⏱️ La generación normalmente toma de 2 a 5 minutos por canción
• 🔁 El servidor MCP maneja todo el sondeo automáticamente
• 🎵 Cada generación siempre crea 2 variaciones de la canción
• 💰 Los créditos (5) se descuentan cuando la solicitud de generación tiene éxito
• ⚠️ Si la generación falla, los créditos NO se consumen

🐛 Solución de Problemas

Problemas Comunes

1. Error de Clave API: Asegúrate de que MUSICMCP_API_KEY esté configurada correctamente

   • Usa la herramienta check_credit_balance para verificar tu clave

2. Créditos Insuficientes (Error 402): No tienes suficientes créditos

   • Verifica tu saldo en https://www.musicmcp.ai
   • Recarga tu cuenta

3. Errores de Tiempo de Espera: Aumenta TIME_OUT_SECONDS si la generación de música tarda más

Registros

Cuando se ejecuta con Claude Desktop, los registros se pueden encontrar en:

• Windows: %APPDATA%\Claude\logs\mcp-server-MusicMCP.AI.log
• macOS: ~/Library/Logs/Claude/mcp-server-MusicMCP.AI.log

🧪 Desarrollo

Ejecutar Pruebas

pytest tests/

Desarrollo Local

python -m musicmcp_ai_mcp.api

Estructura del Código

musicmcp_ai_mcp/
├── __init__.py          # Package initialization
├── __main__.py          # CLI entry point
└── api.py               # Core MCP server implementation (430 lines)

🔗 Enlaces

• Plataforma: https://www.musicmcp.ai
• Documentación: https://www.musicmcp.ai/docs
• Soporte: support@musicmcp.ai

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENCIA para más detalles.

---