Lacuna Music
Gerador de Músicas e Gerador de Letras com IA da Lacuna como ferramentas MCP: gere músicas completas com vocais, escreva letras e busque áudio finalizado de qualquer cliente MCP.
Documentação
1
Obtenha uma chave de API
A Music API requer o plano Pro ou superior. Crie uma chave no seu painel — ela é exibida apenas uma vez, então copie-a diretamente para um gerenciador de segredos. As chaves começam com lyr_live_.
2
Conecte seu cliente
O servidor fala stdio, o transporte MCP padrão, e roda diretamente do npm — não há nada para clonar ou compilar. No Claude Code, um comando o registra:
claude mcp add lacuna \
--env LACUNA_API_KEY=lyr_live_xxx \
-- npx -y lacuna-mcp
Claude Desktop, Cursor, Zed e outros clientes usam o mesmo servidor como uma entrada JSON. Adicione isso ao arquivo de configuração MCP do cliente:
{
"mcpServers": {
"lacuna": {
"command": "npx",
"args": ["-y", "lacuna-mcp"],
"env": {
"LACUNA_API_KEY": "lyr_live_xxx"
}
}
}
}
Defina LACUNA_BASE_URL também se precisar apontar o servidor para um host de API diferente; caso contrário, o padrão está correto.
3
Peça uma faixa
Reinicie o cliente e as ferramentas aparecem. A partir daqui, é linguagem natural — o agente escolhe as ferramentas, consulta a tarefa e devolve uma URL de áudio hospedada.
You: Make me a lofi track for a study playlist — mellow piano,
around 70 bpm, no vocals. Call it "Late Night Study".
Claude: [generate_music] → task gen_cm123abc, status pending
[wait_for_generation] → status ready
Done — here's the track:
https://cdn.lacuna.fm/music/.../late-night-study.mp3
A geração é assíncrona e normalmente leva um ou dois minutos. Os créditos são deduzidos antecipadamente na taxa do modelo selecionado e reembolsados automaticamente se a geração upstream falhar.
Ferramentas expostas ao agente
generate_music
Cria uma tarefa de geração a partir de uma descrição de estilo, letras opcionais e um título.
Retorna imediatamente com uma tarefa pendente. Aceita style\, title\, lyrics\, instrumental\ e model\.
wait_for_generation
Consulta uma tarefa até que ela esteja pronta ou falhe, então retorna as faixas concluídas.
O padrão é um intervalo de 5 segundos e um tempo limite de 10 minutos; ambos são ajustáveis por chamada.
get_generation
Lê o estado atual de uma tarefa pelo id sem bloquear.
Útil quando o agente quer verificar uma tarefa longa entre outros trabalhos.
Escolhendo um modelo
O parâmetro model é opcional. Deixe-o de fora e o agente recebe aether. As taxas de crédito diferem porque os modelos custam valores diferentes para executar, não porque um é de nível superior ao outro.
| Modelo | Para que serve |
|---|---|
| aether | O padrão. Vocais mais controles de peso de estilo; o único modelo que pode estender, cobrir ou substituir seções. |
| echo | Faixas estruturadas completas de até três minutos. A duração é decidida pelo modelo, então não há parâmetro de duração. |
Não usa MCP? Duas outras rotas
Mesma API por baixo — escolha a que se encaixa onde seu agente roda.
Agent Skill
lacuna-music é uma skill empacotada para agentes que leem arquivos SKILL.md. Ela ensina o agente quando usar música e qual transporte utilizar.
SDK & CLI
Para seu próprio backend ou um job de CI, lacuna-sdk é um cliente TypeScript tipado e lacuna-toolkit fornece um comando lacuna.