10. The MCP server (AI assistants)

Nebula can be driven by an AI assistant — Claude Desktop, or anything else that speaks MCP (the Model Context Protocol) — through a small server in the API repository: clients/mcp/. It is a translator, not a brain: it turns tool calls from the assistant into Control API requests (chapter 9) and sends back what Nebula answers. It does not generate music by itself.

Claude Desktop  <-- MCP over stdio -->  the MCP server  <-- the Control API -->  Nebula

You say, in plain language, "add a bass track, give it Sub Bass, and write a four-bar beat on the drums" — the assistant calls tools like nebula_add_track, nebula_set_track_instrument and nebula_add_clip; the server turns each into a request; you watch it happen in the window as it runs, exactly as if you had clicked it yourself.

Setting it up

1. In Nebula: Options > Settings > Local API, switch it on, note the port and copy the token.
2. Install uv (or use a plain Python virtual environment with pip install "mcp<2").
3. Point your MCP client at clients/mcp/nebula_mcp_server.py. For Claude Desktop, add to its config (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "nebula": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\Nebula-Sound-System-API\\clients\\mcp", "nebula_mcp_server.py"],
      "env": { "NEBULA_PORT": "8642", "NEBULA_TOKEN": "paste-the-token-here" }
    }
  }
}

4. Restart your MCP client. Start Nebula whenever suits you — the server also reconnects on its first tool call, so the order does not matter.

What it can do

Around thirty tools, grouped the same way as the Control API itself: reading the project, tracks, clips, notes, the effect catalogue and a track's chain, and history; and writing — tempo, track setup, clips and notes, effects, transport, undo/redo, and rendering to a WAV file.

The safety model

• Every write is one real, undoable edit — the same command-bus path a click takes. Undo (Ctrl+Z in the window, or the assistant's own undo tool) reverts it.
• Destructive tools preview first. Removing a track, a clip, a note or an effect does nothing the first time it is called — it only reports what would be removed. Only a second call, explicitly confirmed, actually removes it. The assistant is instructed to ask you before confirming.
• The token never appears in anything the assistant sees — it is read once from your environment, used only to talk to Nebula, and scrubbed from every reply and error message.
• Localhost only, same as the door itself.
• Numbers, ids and names are checked before they are ever sent, so a mistake is reported clearly instead of silently doing the wrong thing.

Other AI tools

Anything that can run an MCP server over stdio and pass it environment variables can use this the same way — Claude Desktop is simply the most common example today.