AI MUSIC MCP

✨ Recursos

• 🎼 Geração de Música por IA: Gere músicas com base em prompts de texto usando os modelos de IA de última geração do MusicMCP.AI
• 🎵 Modos Duplos de Geração: Suporte para modo inspiração e modo personalizado
• 🔗 Links de Download Direto: Obtenha URLs de download direto para as músicas geradas
• 🎹 Opções Instrumentais: Gere músicas apenas instrumentais ou músicas completas com vocais
• ✅ Verificação de Saldo de Créditos: Verifique a validade da sua chave de API e os créditos restantes
• 🏥 Monitoramento de Saúde: Verifique o status de saúde do serviço de API

🚀 Início Rápido com Claude Desktop

1. Obtenha Sua Chave de API: Obtenha sua chave de API na Plataforma MusicMCP.AI
2. Instale o uv: Instale o gerenciador de pacotes Python com curl -LsSf https://astral.sh/uv/install.sh | sh
3. Configure o Claude: Vá para Claude > Configurações > Desenvolvedor > Editar Configuração > claude_desktop_config.json e adicione:

{
    "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. Reinicie o Claude: Reinicie o aplicativo Claude e você verá 4 ferramentas MCP disponíveis, indicando carregamento bem-sucedido

⚙️ Variáveis de Ambiente

Variável	Descrição	Padrão	Obrigatória
MUSICMCP_API_KEY	Sua chave de API do MusicMCP.AI	-	✅ Sim
MUSICMCP_API_URL	URL base da API do MusicMCP.AI	https://www.musicmcp.ai/api	❌ Não
TIME_OUT_SECONDS	Tempo limite para geração de música em segundos	600 (10 min)	❌ Não

🛠️ Ferramentas Disponíveis

1. 🎼 Gerar Música por Prompt (Modo Inspiração)

Gere música por IA com base em descrições de texto simples. A IA cria automaticamente título, letra e estilo.

Custo: 5 créditos por geração (cria 2 músicas)

Parâmetros:

• prompt (str): Descrição simples do tema da música (1-1200 caracteres)
• instrumental (bool): Se deve gerar apenas música instrumental
• style (str, opcional): Estilo musical (ex.: "ambient", "pop", "rock")

Exemplos de Prompts:

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

Exemplo de Saída:

✅ 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. 🎵 Gerar Música Personalizada (Modo Personalizado)

Gere música por IA com letras, título e parâmetros de estilo específicos que você fornece.

Custo: 5 créditos por geração (cria 2 músicas)

Parâmetros:

• title (str): Título da música (obrigatório)
• instrumental (bool): Se deve gerar apenas música instrumental (obrigatório)
• lyric (str, opcional): Conteúdo completo da letra (não necessário quando instrumental é true)
• tags (str, opcional): Tags de estilo musical (ex.: 'pop', 'rock', 'folk')

Exemplo 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

Exemplo de Saída:

✅ 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

Verifique se sua chave de API é válida e veja seus créditos restantes.

Custo: Grátis

Exemplo de Uso:

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

4. 🏥 Verificar Saúde da API

Monitore o status de saúde do serviço de API do MusicMCP.AI.

Custo: Grátis

Exemplo de Uso:

"Check API service status"

💰 Créditos e Preços

Operação	Custo em Créditos	Saída
Gerar Música por Inspiração	5 créditos	2 músicas
Gerar Música Personalizada	5 créditos	2 músicas
Consultar Status da Música	0 créditos (Grátis)	-
Verificar Saldo de Créditos	0 créditos (Grátis)	-
Verificação de Saúde da API	0 créditos (Grátis)	-

💡 Exemplo de Uso

⚠️ Nota: Créditos do MusicMCP.AI são necessários para usar as ferramentas de geração de música.

Experimente perguntar ao Claude:

Modo Inspiração:

• "Por favor, me ajude a gerar uma música sobre uma manhã tranquila"
• "Quero uma música que expresse saudade"
• "Crie música sobre amizade"
• "Gere uma faixa de música ambiente"

Modo Personalizado:

• "Por favor, me ajude a gerar uma música, Título: Summer Dreams, Letra: [letra completa], Estilo: folk"
• "Crie uma música, Título: Spring Promise, Letra: [letra completa], Estilo pop"
• "Gere uma música instrumental, Título: Ocean Breeze, Estilo: ambient"

Funções de Gerenciamento:

• "Verifique meu saldo de créditos"
• "Quantos créditos ainda tenho?"
• "Verifique o status do serviço de API"

📦 Instalação

Usando uv (Recomendado)

uvx aimusic-mcp

Usando pip

pip install aimusic-mcp

🔌 Integração com API

Este servidor MCP integra-se com a API RESTful do MusicMCP.AI:

• POST /music/generate/inspiration: Criar tarefa de geração de música (modo inspiração)
• POST /music/generate/custom: Criar tarefa de geração de música personalizada
• POST /music/generate/query: Consultar status da música (consulta em lote suportada)
• GET /credit: Verificar saldo de créditos
• GET /health: Verificar saúde do serviço de API

🔄 Fluxo de Trabalho Assíncrono da API

A geração de música é assíncrona. O servidor MCP lida com isso automaticamente:

Etapa 1: Enviar Solicitação de Geração

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

Etapa 2: Polling Automático (tratado internamente pelo 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

Etapa 3: Retornar Informações Completas da Música

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

Nos Bastidores:

1. O usuário chama generate_prompt_song() ou generate_custom_song()
2. O MCP envia a solicitação de geração → recebe 2 IDs de músicas
3. O MCP consulta automaticamente /music/generate/query a cada 2 segundos
4. Quando todas as músicas são concluídas (status=1), retorna as URLs de download
5. Tempo limite padrão: 10 minutos (configurável via TIME_OUT_SECONDS)

Notas Importantes:

• ⏱️ A geração normalmente leva de 2 a 5 minutos por música
• 🔁 O servidor MCP lida com todo o polling automaticamente
• 🎵 Cada geração sempre cria 2 variações da música
• 💰 Os créditos (5) são deduzidos quando a solicitação de geração é bem-sucedida
• ⚠️ Se a geração falhar, os créditos NÃO são consumidos

🐛 Solução de Problemas

Problemas Comuns

1. Erro de Chave de API: Certifique-se de que MUSICMCP_API_KEY esteja configurada corretamente

   • Use a ferramenta check_credit_balance para verificar sua chave

2. Créditos Insuficientes (Erro 402): Você não tem créditos suficientes

   • Verifique seu saldo em https://www.musicmcp.ai
   • Recarregue sua conta

3. Erros de Tempo Limite: Aumente TIME_OUT_SECONDS se a geração de música demorar mais

Logs

Ao executar com Claude Desktop, os logs podem ser encontrados em:

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

🧪 Desenvolvimento

Executando Testes

pytest tests/

Desenvolvimento Local

python -m musicmcp_ai_mcp.api

Estrutura do Código

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

🔗 Links

• Plataforma: https://www.musicmcp.ai
• Documentação: https://www.musicmcp.ai/docs
• Suporte: support@musicmcp.ai

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

---