Lacuna MCP

lacuna-mcp

适用于 Lacuna Music API 的 Model Context Protocol 服务。它可让 MCP 兼容客户端（Claude Desktop、Claude Code、Cursor、Zed、Continue 等）在 Agent 循环中生成 AI 音乐。

想要 SDK 或 CLI？请参阅 lacuna-sdk 和 lacuna-toolkit。

---

安装

此服务以单个 npm 软件包的形式发布，通过 stdio 运行。无需安装步骤——你的 MCP 客户端会通过 npx 启动它。

npx lacuna-mcp

配置

此服务通过环境变量读取配置：

变量	必填	描述
LACUNA_API_KEY	是	从个人资料控制面板获取的 API 密钥。以 lyr_live_ 开头。
LACUNA_BASE_URL	否	覆盖 API 基础 URL（例如用于暂存环境）。

音乐 API 访问需要 Pro 计划或更高级别的计划。

Claude Desktop

在 claude_desktop_config.json 中添加一项：

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

配置文件位于：

• 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

然后在 shell 中导出密钥，或通过客户端的 MCP 设置进行配置。

Cursor / Zed / 其他 MCP 客户端

任何通过 stdio 使用 Model Context Protocol 的客户端，都可以将 npx -y lacuna-mcp 作为命令运行，并将 LACUNA_API_KEY 作为环境变量传入。具体 JSON 格式请参阅客户端的 MCP 设置文档。

---

工具

工具	描述
generate_music	创建音乐生成任务。立即返回一个 pending 任务。
get_generation	按 ID 获取生成任务的当前状态。
wait_for_generation	轮询任务，直到任务进入终止状态（ready 或 failed）或超时。

generate_music

Parameter	Type	Description
style	string (required)	风格描述，例如 "pop, female vocal, 120 bpm, energetic"。
title	string (required)	曲目标题。
lyrics	string	除非 instrumental 为 true，否则必填。
instrumental	boolean	生成纯音乐曲目。默认为 false。
model	"aether" | "echo"	生成模型。默认为 aether（Lacuna Aether）。
vocal_gender	"m" | "f"	主唱性别提示（仅限 aether）。
negative_tags	string	要避免的风格标签（仅限 aether）。
style_weight	number (0–1)	仅限 aether。
weirdness_constraint	number (0–1)	仅限 aether。
audio_weight	number (0–1)	仅限 aether。

创建时会扣除积分；如果上游提供商失败，积分将自动退还。

get_generation

Parameter	Type	Description
id	string	生成任务 ID，由 generate_music 返回。

wait_for_generation

Parameter	Type	Description
id	string	生成任务 ID。
poll_interval_seconds	number	轮询间隔。默认为 5。
timeout_seconds	number	总超时时间。默认为 600（10 分钟）。

---

要求

• Node.js 18 或更高版本。
• Lacuna Pro 或更高级别套餐的 API 密钥。

---

许可证

MIT © Louis Tsang