io.github.JOYLINK-LTD/lacuna-mcp: Lacuna Music MCP Server

This MCP server generates AI music via the Lacuna Music API from MCP-compatible clients such as Claude Desktop and Claude Code. It is intended to be used as part of an agent loop, enabling music-generation actions through MCP integrations.

🛠️ Key Features

Model Context Protocol (MCP) server
AI music generation using the Lacuna Music API
Exposed as an npm package (MIT license noted in the excerpt)
toolCount: 3

🚀 Use Cases

Generate AI music from MCP clients (e.g., Claude Desktop, Claude Code)
Use in an agent loop to produce music programmatically

⚡ Developer Benefits

MCP compatibility for multiple clients (Claude Desktop, Claude Code, Cursor, Zed, Continue listed)
TypeScript/SDK-oriented ecosystem indicated by topics (e.g., sdk, mcp-server, typescript)

⚠️ Limitations

Limited to music generation through the Lacuna Music API, as described in the excerpt
The excerpt does not enumerate the 3 tools individually

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:

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.

Lacuna Music

io.github.JOYLINK-LTD/lacuna-mcp: Lacuna Music MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

generate_music

get_generation

list_models

lacuna-mcp

Installation

Configuration

Claude Desktop

Claude Code

Cursor / Zed / other MCP clients

Tools

`generate_music`

`get_generation`

`wait_for_generation`

Requirements

License

Install

Configuration

Related servers

style	string	required	Style description, e.g. "pop, female vocal, 120 bpm, energetic".
title	string	required	Track title.
lyrics	string	optional	Lyrics in plain text. Required unless `instrumental` is true.
instrumental	boolean	optional	Generate an instrumental track (no lyrics). Defaults to false.
model	string	optional	Generation model. Defaults to `aether`. Call `list_models` for what each one covers.
vocal_gender	string	optional	Lead vocal gender hint (aether only).
negative_tags	string	optional	Negative style tags to avoid (aether only).
style_weight	number	optional	Style weight 0–1 (aether only).
weirdness_constraint	number	optional	Weirdness constraint 0–1 (aether only).
audio_weight	number	optional	Audio reference weight 0–1 (aether only).