Csound MCP Server

The Csound MCP server exposes Csound audio engine functionality to AI agents via the Model Context Protocol (MCP).

Features

• Stateless Architecture: Lightweight execution using standard Csound.
• Subtractive Synthesis: Exposes a synthesize_sawtooth_lead_bass tool that provides LLM-friendly 0-255 mapped ADSR parameters to shape a sawtooth oscillator run through a lowpass filter.
• Drum Synthesis: Exposes a synthesize_kick_drum tool specialized for crafting Sub Basses, punchy House kicks, and distorted Hardstyle kicks using intuitive parameters like punch and drive.
• Semantic Guardrails: The tool parameters are heavily documented with acoustic definitions (e.g., matching "fast attack" to integer ranges), and MCP Resources (lore://sound_design, lore://drum_design) are provided to teach agents how to synthesize classic instruments.
• Error Handling: Gracefully captures and returns stdout and stderr content to the agent if csound compilation or execution fails.

Prerequisites

• uv package manager
• csound installed and available in the system $PATH

Installation & Running

The package is built with Python and depends on mcp. You can run the server directly using uv:

uv run musmcp

Adding to an MCP Client

To configure this server in an MCP client (such as Claude Desktop or Cursor), add it to your configuration (adjust the root path to your workspace directory):

{
  "mcpServers": {
    "musmcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/workspace/musmcp",
        "run",
        "musmcp"
      ]
    }
  }
}

Usage Example (Agent perspective)

Before using the synthesis tools, an agent can read the provided lore://sound_design and lore://drum_design MCP resources to understand how to map acoustic concepts to the 0-255 integers.

1. synthesize_sawtooth_lead_bass

The synthesize_sawtooth_lead_bass tool is specifically designed to be easy for LLM agents to use. It abstracts complex Csound envelopes into simple 0-255 integers.

Here is how an agent should map desired sounds to the tool's parameters:

1. A Plucky/Percussive Bass (Fast attack, fast decay, no sustain)

{
  "pitch": 55.0,
  "duration": 1.5,
  "cutoff_hz": 400.0,
  "attack": 5,
  "decay": 80,
  "sustain": 0,
  "release": 50,
  "output_filename": "bass_pluck.wav"
}

2. A Warm Pad (Slow attack, high sustain, long release)

{
  "pitch": 220.0,
  "duration": 4.0,
  "cutoff_hz": 1200.0,
  "attack": 150,
  "decay": 100,
  "sustain": 200,
  "release": 200,
  "output_filename": "warm_pad.wav"
}

3. An Aggressive Lead (Fast attack, high sustain, bright filter)

{
  "pitch": 880.0,
  "duration": 2.0,
  "cutoff_hz": 4500.0,
  "attack": 10,
  "decay": 50,
  "sustain": 255,
  "release": 20,
  "output_filename": "aggr_lead.wav"
}

2. synthesize_kick_drum

A dedicated tool for creating everything from soft acoustic thumps to booming 808s and distorted hard kicks.

1. 808 Sub Kick (Booming, no hard click)

{
  "fundamental_hz": 45.0,
  "punch": 20,
  "decay": 220,
  "drive": 10,
  "output_filename": "808_sub.wav"
}

2. Hardstyle / Industrial Kick (Heavily distorted with massive click)

{
  "fundamental_hz": 50.0,
  "punch": 200,
  "decay": 150,
  "drive": 220,
  "output_filename": "hard_kick.wav"
}