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" | Generation model. Defaults to aether (Lacuna Aether). | | vocal_gender | "m" \| "f" | Lead vocal hint. | | negative_tags | string | Style tags to avoid. | | style_weight | number (0–1) | | | weirdness_constraint | number (0–1) | | | audio_weight | number (0–1) | |

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