MCP Server

Give your coding agent
a music studio.

lacuna-mcp is the official Model Context Protocol server for the Lacuna Music API. Point Claude Code, Claude Desktop, Cursor, or any MCP client at it and your agent can score a demo, write a jingle, or fill a playlist without leaving the conversation.

Create API key lacuna-mcp on npm Source

Get an API key

The Music API requires the Pro plan or above. Create a key in your dashboard — it is shown once, so copy it straight into a secrets manager. Keys begin with lyr_live_.

Open dashboard View pricing

Connect your client

The server speaks stdio, the standard MCP transport, and runs straight from npm — there is nothing to clone or build. In Claude Code, one command registers it:

claude mcp add lacuna \
  --env LACUNA_API_KEY=lyr_live_xxx \
  -- npx -y lacuna-mcp

Claude Desktop, Cursor, Zed, and other clients take the same server as a JSON entry. Drop this into the client's MCP configuration file:

{
  "mcpServers": {
    "lacuna": {
      "command": "npx",
      "args": ["-y", "lacuna-mcp"],
      "env": {
        "LACUNA_API_KEY": "lyr_live_xxx"
      }
    }
  }
}

Set LACUNA_BASE_URL as well if you need to point the server at a different API host; otherwise the default is correct.

Ask for a track

Restart the client and the tools appear. From here it is plain language — the agent picks the tools, polls the task, and hands back a hosted audio URL.

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

Generation is asynchronous and typically takes a minute or two. Credits are deducted up-front at the selected model's rate and refunded automatically if the upstream generation fails.

Tools exposed to the agent

generate_music

Create a generation task from a style description, optional lyrics, and a title.

Returns immediately with a pending task. Accepts `style`, `title`, `lyrics`, `instrumental`, and `model`.

wait_for_generation

Poll a task until it is ready or failed, then return the finished tracks.

Defaults to a 5-second interval and a 10-minute timeout; both are adjustable per call.

get_generation

Read the current state of a task by id without blocking.

Useful when the agent wants to check on a long task between other work.

Choosing a model

The model parameter is optional. Leave it out and the agent gets aether. Credit rates differ because the models cost different amounts to run, not because one is a higher tier than the other.

Model	What it is for
aether	The default. Vocals plus style-weight controls; the only model that can extend, cover, or replace sections.
echo	Full structured tracks up to three minutes. Length is decided by the model, so no duration parameter.

Not using MCP? Two other routes

Same API underneath — pick whichever fits where your agent runs.

Agent Skill

lacuna-music is a packaged skill for agents that read SKILL.md files. It teaches the agent when to reach for music and which transport to use.

View the skill

SDK & CLI

For your own backend or a CI job, lacuna-sdk is a typed TypeScript client and lacuna-toolkit gives you a lacuna command.

Read the quickstart