<p align="right"> English | <a href="README.ko.md">한국어</a> | <a href="README.ja.md">日本語</a> </p>

PureData-MCP

<p align="center"> <img src="icon.png" width="160" alt="PureData-MCP icon"> </p>

Control and live-patch Pure Data from AI agents via the Model Context Protocol.

PureData-MCP lets an MCP client start Pd, open visible GUI patches, generate Vanilla .pd patches, and edit objects and connections while a patch is running. The goal is simple: ask for sound in natural language, watch Pd become the instrument.

Pure Data, also known as Pd or Pd Vanilla, is the open-source visual programming language for multimedia created by Miller Puckette and maintained by the Pd community. This project is independent and is not affiliated with or endorsed by the Pure Data project. Many thanks to the Pure Data creators and community for making this kind of work possible.

Quick Start

Install Pure Data and Node.js 20 or newer, then run the MCP server with npm:

npx -y @damagethundercat/puredata-mcp

Most users do not run that command directly. Instead, add it to an MCP client such as Codex, Claude Code, Cursor, or VS Code.

Connect To Codex

Add this to your Codex MCP config:

[mcp_servers.puredata]
command = "npx"
args = ["-y", "@damagethundercat/puredata-mcp"]

On Windows, use cmd /c so the MCP client avoids PowerShell npm policy issues:

[mcp_servers.puredata]
command = "cmd"
args = ["/c", "npx", "-y", "@damagethundercat/puredata-mcp"]

Restart Codex after changing the config.

Other MCP Clients

For clients that use JSON MCP config, add:

{
  "mcpServers": {
    "puredata": {
      "command": "npx",
      "args": ["-y", "@damagethundercat/puredata-mcp"]
    }
  }
}

On Windows:

{
  "mcpServers": {
    "puredata": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@damagethundercat/puredata-mcp"]
    }
  }
}

Try It

After connecting the server, ask your agent:

Create a visible Pure Data patch with an osc~ -> *~ -> dac~ signal chain.

Make a 120 BPM electronic loop with kick, hi-hat, bass, a mixer, and dac~ in one Pure Data GUI window.

Add a delay effect to the current patch and keep the output quiet.

Move the bass section to the left, remove the old hi-hat object, and reconnect the mixer.

What It Can Do

• Start and stop local Pure Data.
• Open Pd headless or with the visible Pd GUI.
• Generate small Vanilla .pd patches.
• Control frequency, amplitude, gate, and DSP over TCP FUDI.
• Open existing .pd files and manage bridge patches that can be live-edited from an already visible Pd GUI.
• Add, connect, move, update, remove, replace, clear, and inspect agent-owned live patch graphs.
• List audio devices and inspect session status/logs.

Tools

PureData-MCP exposes a small set of MCP tools:

• Lifecycle: pd_start_demo, pd_stop, pd_status
• Patch lifecycle: pd_open_patch, pd_start_live_session, pd_create_live_patch, pd_attach_live_session, pd_save_patch
• Audio/control: pd_set_params, pd_send_control, pd_list_audio_devices
• Patch preview: pd_preview_patch
• Live GUI editing: pd_live_add_object, pd_live_connect, pd_live_move_object, pd_live_update_object, pd_live_remove_object, pd_live_disconnect, pd_live_replace_graph, pd_live_clear, pd_live_graph

The live editing tools let an agent build and modify a visible Pure Data patch while it is running.

For full musical patches, generate a complete safe graph first and apply it with pd_live_replace_graph in one call. Use the object-by-object tools for small follow-up edits, and use pd_send_control for designed live parameters such as cutoff, amp, mix, or mode.

Resources

• pd://session/status
• pd://patch/current
• pd://logs/recent
• pd://schema/parameters
• pd://live/graph

Local Demos

Clone the repository if you want to run the included demos directly:

git clone https://github.com/damagethundercat/PureData-MCP.git
cd PureData-MCP
npm install
npm run build

Run the current electronic rhythm demo:

npm run demo:electro

On Windows PowerShell, prefer:

cmd /c npm run demo:electro

The demo patch lives at patches/electro-rhythm-loop.pd.

Development

npm run test:unit
npm run typecheck
npm run build

Opt-in Pd integration tests:

PD_INTEGRATION=1 PD_EXE="/path/to/pd" npm run test:pd

On Windows:

$env:PD_EXE="C:\Program Files\Pd\bin\pd.com"
$env:PD_INTEGRATION="1"
cmd /c npm run test:pd

Troubleshooting

• If Pd is not found, set PD_EXE for headless sessions or PD_GUI_EXE for visible GUI sessions.
• If audio is silent or routed to the wrong device, ask the agent to run pd_list_audio_devices, then start again with the right audioOutDevice.
• If PowerShell blocks npm scripts on Windows, run npm through cmd /c npm ....

License

MIT