lacuna-mcp

lacuna-mcp

Model Context Protocol server for the Lacuna Music API. Lets MCP-compatible clients (Claude Desktop, Claude Code, Cursor, Zed, Continue, etc.) generate AI music as part of an agent loop.

Looking for the SDK or CLI? See lacuna-sdk and lacuna-toolkit.

Installation

The server is published as a single npm package and runs over stdio. No install step is needed — your MCP client launches it via npx.

npx lacuna-mcp

Configuration

The server reads its configuration from environment variables:

Variable	Required	Description
LACUNA_API_KEY	yes	API key from your profile dashboard. Begins with lyr_live_.
LACUNA_BASE_URL	no	Override the API base URL (e.g. for staging).

Music API access requires the Pro plan or above.

Claude Desktop

Add an entry to claude_desktop_config.json:

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

The config file lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

claude mcp add lacuna -- npx -y lacuna-mcp

Then export the key in your shell or set it via your client's MCP settings.

Cursor / Zed / other MCP clients

Any client that speaks the Model Context Protocol over stdio can run npx -y lacuna-mcp as the command and pass LACUNA_API_KEY as an env var. Refer to your client's MCP setup docs for the exact JSON shape.

Tools

Tool	Description
generate_music	Create a music generation task. Returns a pending task immediately.
get_generation	Retrieve the current state of a generation task by id.
wait_for_generation	Poll a task until it reaches a terminal state (ready or failed) or the timeout elapses.

generate_music

Parameter	Type	Description
style	string (required)	Style description, e.g. "pop, female vocal, 120 bpm, energetic".
title	string (required)	Track title.
lyrics	string	Required unless instrumental is true.
instrumental	boolean	Generate an instrumental track. Default false.
model	"aether" | "echo"	Generation model. Defaults to aether (Lacuna Aether).
vocal_gender	"m" | "f"	Lead vocal hint (aether only).
negative_tags	string	Style tags to avoid (aether only).
style_weight	number (0–1)	aether only.
weirdness_constraint	number (0–1)	aether only.
audio_weight	number (0–1)	aether only.

Credits are deducted on creation and refunded automatically if the upstream provider fails.

get_generation

Parameter	Type	Description
id	string	Generation task id, returned by generate_music.

wait_for_generation

Parameter	Type	Description
id	string	Generation task id.
poll_interval_seconds	number	Polling interval. Default 5.
timeout_seconds	number	Total timeout. Default 600 (10 minutes).

Requirements

• Node.js 18 or newer.
• An API key from a Lacuna Pro plan or above.

License

MIT © Louis Tsang