puredata

puredata-mcp

A reliable Model Context Protocol server for Pure Data. It lets an MCP client (Claude Desktop, etc.) build and drive Pd patches in natural language: create objects, wire them together, toggle audio, and send live messages into a running patch. It also keeps an authoritative in-memory model of the patch, so it can version your work — git-backed checkpoints, standalone .pd export, and a musical graph-level diff between versions.

Why this design is reliable

It speaks Pd's native FUDI protocol over a plain TCP socket and uses Pd vanilla's built-in dynamic patching messages (obj, msg, connect, disconnect, clear). That means:

• No externals to install (no mrpeach/OSC, no zexy, no namecanvas).
• No intermediate daemon — the MCP server talks straight to [netreceive].
• Object ids stay in sync with Pd because the server mirrors Pd's exact creation-index ordering.

Earlier OSC-based Pd MCP attempts were fragile precisely because they stacked an OSC layer plus a relay daemon on top of Pd. This removes both.

Architecture

 Claude / MCP client
        │  (stdio, JSON-RPC)
        ▼
 puredata_mcp.server  ──FUDI over TCP──▶  [netreceive 3000]   (mcp_host.pd)
                                               │
                                          [route __dsp __send]
                                          │     │          └─▶ [send pd-canvas] ─▶ [pd canvas]
                                          │     └─▶ relay ─▶ [send] (to a named [receive])
                                          └─▶ [; pd dsp $1(   (global audio on/off)

Objects you create land inside the [pd canvas] subpatch, addressed by Pd's dynamic-patching receiver pd-canvas.

Install

Pick the channel that matches your client. The repo ships in three formats so each lands cleanly:

Client	How to install	What it activates
Claude Code (CLI REPL)	inside a claude session: /plugin marketplace add jfboisvenue/pd-mcp-server then /plugin install puredata@puredata-marketplace	Skill auto-load + 30 MCP tools
Claude Desktop — Cowork sessions	Plugins panel → "Add from repository" → paste https://github.com/jfboisvenue/pd-mcp-server	Skill auto-load + 30 MCP tools (Cowork chat only)
Claude Desktop — regular chat	Download puredata-mcp.mcpb from Releases → double-click → Install via Settings → Extensions	30 MCP tools (no skill — the plugin/skill format isn't loaded by this channel)

You can install both — the plugin (Code + Cowork) and the .mcpb (regular Desktop chat) coexist, share the same source code, and don't conflict.

After install, the skill (where applicable) auto-loads when relevant and the MCP tools become available. You still need to open pd/mcp_host.pd in Pd for the server to have something to talk to.

Why three channels?

Anthropic's plugin marketplace targets Claude Code and Desktop's Cowork sessions. Plugins installed this way load their skill in regular Desktop chat too, but not the MCP server — that's by design across all platforms (macOS, Windows, Linux), not a Linux-specific bug. For the MCP to appear in regular Desktop chat, you need either a .mcpb Desktop Extension or a manual entry in ~/.config/Claude/claude_desktop_config.json (see Manual MCP install below).

Local dev / testing

For iteration on the code itself:

claude --plugin-dir /absolute/path/to/pd-mcp-server   # per-session

Or symlink once, persistent across sessions and surfaces:

mkdir -p ~/.claude/skills && \
ln -s /absolute/path/to/pd-mcp-server ~/.claude/skills/puredata

Requirements

For the MCP core (object/wire/DSP tools):

• Pure Data vanilla 0.51+
• Python 3.10+ to run the MCP server
• uv (recommended) or pip

For the Python tools (pd_create_python_object, pd_update_python_script) the user's Pd host machine additionally needs:

• Pure Data vanilla ≥ 0.56 — py4pd 1.2.3 uses pd_snprintf, missing in 0.54.x and earlier (symptom: undefined symbol: pd_snprintf / couldn't create).
• py4pd external ≥ 1.2.3 installed in Pd (Help → Find externals → "py4pd").
• Python 3.14 installed system-wide — py4pd's Deken build links against libpython3.14.so.1.0. On Ubuntu 24.04 (which ships 3.12 by default) you may need to install 3.14 separately (e.g. deadsnakes PPA).
• The host patch must contain [declare -path <scripts dir> -lib py4pd]. The bundled pd/mcp_host.pd already does this; custom host patches need it added.

Verified working stack: Pd 0.56-3 + py4pd 1.2.3 + Python 3.14.5 + .pd_py classes inheriting pd.NewObject.

Manual MCP install (fallback)