lacuna-music — Claude Code plugin: what it does, how to install
lacuna-music generates instrumental tracks and vocal songs from text prompts using the Lacuna MCP server. Useful when you need custom audio or mock soundtracks inside your agent.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install lacuna-music@awesome-codex-pluginsWhat lacuna-music does
The plugin launches the pinned [email protected] package over stdio. It equips Claude Code and Codex with three MCP tools: generate_music to trigger new jobs, get_generation to inspect status, and wait_for_generation to poll for final audio URLs. You can specify style details for instrumentals or supply lyrics to build a sung track.
Audio requests complete asynchronously. The MCP server returns a pending task identifier right away, expecting poll intervals of roughly 10 seconds. Each generation consumes credits from the active Lacuna profile.
Running this requires Node.js 18 or newer, an active Lacuna account on Pro tier or higher, and a LACUNA_API_KEY granted the music:generate permission scope. Without a paid Pro subscription, generation requests fail.
What it helps with
- produce instrumental audio from a genre description
- generate a vocal song using custom lyrics
- poll task progress and retrieve generated audio links
Example prompts for the agent
- Compose an upbeat lo-fi instrumental track for background music
- Turn these lyrics into an indie rock song with vocals
- Check the status of the current music generation task
How to install lacuna-music
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install lacuna-music@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about lacuna-music
How to install lacuna-music in Claude Code?
Run /plugin marketplace add hashgraph-online/awesome-codex-plugins followed by /plugin install lacuna-music@awesome-codex-plugins. Then set your LACUNA_API_KEY environment variable.
What does the lacuna-music plugin do?
It connects your coding agent to Lacuna's MCP server, enabling text-to-music generation for instrumentals and vocal tracks.
What prerequisites are needed?
You need Node.js 18 or newer, a Lacuna Pro subscription or higher, and a LACUNA_API_KEY configured with the music:generate scope.
Source text
lacuna-plugin · MIT
# Lacuna Music Plugin Generate original instrumental music and vocal songs from Claude Code or Codex using Lacuna's published Model Context Protocol server. ## Capabilities - Generate an instrumental from a natural-language style description. - Turn supplied lyrics into a complete song with vocals. - Retrieve a generation or wait until its audio URLs are ready. Music generation spends credits from the authenticated Lacuna account. The MCP server returns a pending task immediately; clients should poll approximately every 10 seconds rather than busy-looping. ## Requirements - A [Lacuna account](https://www.lacuna.fm/login) on Pro or higher. - A `LACUNA_API_KEY` created at [Lacuna API settings](https://www.lacuna.fm/profile/api) with the `music:generate` scope. - Node.js 18 or newer so the client can launch the pinned `[email protected]` package. ## Install in Claude Code ```sh /plugin marketplace add JOYLINK-LTD/lacuna-plugin /plugin install lacuna-music@lacuna ``` Export `LACUNA_API_KEY` in the environment Claude Code runs in, then run `/reload-plugins` if the install summary asks for it. ## Install in Codex ```sh codex plugin marketplace add JOYLINK-LTD/lacuna-plugin codex plugin add lacuna-music@lacuna ``` Make `LACUNA_API_KEY` available to Codex, restart the app, and test the plugin in a new task. ## Tools | Tool | Purpose | | --- | --- | | `generate_music` | Creates a generation task and returns its pending task ID. | | `get_generation` | Retrieves the current state of a generation task. | | `wait_for_generation` | Polls until a task becomes `ready` or `failed`. | ## Repository layout - `.claude-plugin/marketplace.json` — installable Claude Code marketplace. - `.claude-plugin/plugin.json` — Claude Code plugin manifest (MCP server declared inline). - `.agents/plugins/marketplace.json` — installable Codex marketplace. - `.codex-plugin/plugin.json` — Codex plugin manifest. - `.mcp.json` — pinned stdio MCP connection (Codex schema; Claude Code reads its own copy from `.claude-plugin/plugin.json`). See the [MCP documentation](https://www.lacuna.fm/docs/mcp) and [Lacuna Toolkit](https://github.com/JOYLINK-LTD/lacuna-toolkit) for the SDK, CLI, and standalone MCP package. ## Security Do not commit or paste a Lacuna API key into this repository. See [SECURITY.md](SECURITY.md) for reporting instructions. ## License MIT
© JOYLINK LTD · MIT · hashgraph-online/awesome-codex-plugins