maxmsp-mcp — State-of-the-Art MCP Server for Max/MSP

Control Max/MSP patches from natural language. 75 tools, zero externals, Python-based. Build, analyze, modify, and debug Max patches through an LLM agent.

pip install uv
git clone https://github.com/pawelknorps/maxmsp-mcp
cd maxmsp-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

Then open max/mcp_host.maxpat in Max and connect your MCP client.

Why This Server?

Quick Start

1. Install

# Requires Python 3.11+ and uv
uv venv
source .venv/bin/activate
uv pip install -e .

2. Open the host patch in Max

Open max/mcp_host.maxpat in Max 9+ (or Max 8+). Turn on DSP.

3. Connect your MCP client

Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "maxmsp": {
      "command": "uv",
      "args": ["--directory", "/path/to/maxmsp-mcp", "run", "python", "-m", "maxmsp_mcp.server"],
      "env": {
        "MAX_HOST": "127.0.0.1",
        "MAX_PORT": "7400",
        "MAX_RETURN_PORT": "7401"
      }
    }
  }
}

4. Start patching

The LLM will call max_init() first to get the orientation guide, then you can:

• "Create a 440Hz sine wave oscillator connected to dac~"
• "Add a delay effect with 300ms and 0.4 feedback"
• "Analyze this patch for safety issues"
• "Encapsulate the filter section into a subpatcher"
• "What's the current tempo in Live?"

Tools Reference (75 tools + 4 prompts)

Core (19) — max_init, max_build_patch etc.

Undo (6)

Subpatcher Navigation (3)

Multi-Patcher (3)

Encapsulation (1)

Attributes & Scripting (3)

UI Creation (7)

Snapshots (2)

Search & Analysis (5)

Safety & Validation (3)

Modification (5)

File & DSP (2)

Templates (3)

Console Feedback (4)

Ableton Live Bridge (4)

MCP Prompts (4)

Architecture

MCP Client (Claude, Cursor, etc.)
    ↕ JSON-RPC over stdio
maxmsp_mcp.server (Python, FastMCP)
    ↕ OSC over UDP (port 7400 → Max, 7401 ← Max)
max/mcp_host.maxpat (Max/MSP patch)
    ↕ [udpreceive] → [route] → [thispatcher]
Max/MSP

Everything runs on stock Max objects — no externals, no compilation, no npm install (except for the optional chat.js). The Python server sends OSC messages to Max's [udpreceive], which routes them through [thispatcher] scripting commands.

Files

maxmsp-mcp/
├── maxmsp_mcp/
│   ├── server.py          # Core server (19 tools)
│   ├── extensions.py      # Extension tools (56 tools, 4 prompts)
│   ├── operations.py      # Undo/redo history system
│   ├── patch_state.py     # Patch state tracking + subpatcher stack
│   ├── templates.py       # 6 patch templates
│   ├── transport.py       # OSC UDP transport layer
│   └── guide.py           # GUIDE.md contents as Python module
├── max/
│   ├── mcp_host.maxpat    # Main host patch (19 OSC routes)
│   ├── dump.js            # Chunked patch dumper (V8 JS)
│   ├── chat.js            # Optional in-Max chat interface
│   ├── console_capture.maxpat  # Console logger (port 7402)
│   └── live_bridge.maxpat      # Ableton Live bridge (port 7403)
├── tests/                 # Test suite
├── pyproject.toml
└── README.md

Roadmap

v0.9 ✓ — Current

• 75 tools across 21 categories
• Undo/redo with batch semantics
• 6 patch templates + 4 MCP prompts
• Safety analysis, feedback loop detection
• Multi-patcher navigation
• Object encapsulation
• Console feedback (clear, error count, log)
• Ableton Live bridge (tempo, track, send)
• 19 OSC routes (all wired)
• Chunked dump for large patches
• Self-healing connection retry

v1.0 — Next

• Test suite (pytest for all 75 tools)
• CI/CD (GitHub Actions)
• Auto-init (detect Max on first tool call)
• Real DSP state readback (/dspstatus OSC route)
• Persistent object naming for stable references
• RNBO compilation tools
• Jitter/GL matrix operations
• Max Package release
• Homebrew tap

Credits

Built on the shoulders of:

• tiianhk — Original MaxMSP-MCP-Server (230 ★)
• ersatzben — Extended fork with safety features (126 ★)
• gluon — FastMCP-based server architecture
• jpoindexter — ableton-mcp Live API bridge (32 ★)

License

MIT