MaxMSP-MCP Server (Extended Fork)

This project uses the Model Context Protocol (MCP) to let LLMs directly understand and generate Max patches.

Fork Notice: This is an extended fork of the original MaxMSP-MCP-Server by Haokun Tian and Shuoyang Zheng. See Acknowledgements for details.

What's New in This Fork

This fork significantly extends the original with new tools, safety features, and Claude Code integration:

New MCP Tools (+11)

Safety & Validation Features

• Float enforcement: Math objects (+, -, *, /, %, pow, scale) and pack/unpack objects require float arguments. Use STRING args to preserve floats (JSON strips .0): ["0", "127", "0", "25."]. Use int_mode=True to explicitly allow integers. Exception: scale with output range ≤ 2 auto-detects float intent.
• dial range enforcement: Rejects live.dial (suggests dial with inline attributes); requires @size on dial objects; rejects @size > 255 (unusable UI - use extend=True to bypass)
• trigger/t acknowledgment: Requires trigger_rtl=True flag to confirm understanding that outlets fire right-to-left
• random acknowledgment: Requires random_bang=True flag to confirm understanding that numbers set range but bangs trigger output
• coll embed enforcement: Requires @embed 1 in args to ensure data persists on save
• line~ message validation: Rejects messages with odd numeric count (likely malformed target-time pairs)
• Object validation: Rejects invalid objects (e.g., times~ → suggests *~)
• Argument validation: Enforces minimum arguments for complex objects (e.g., comb~ requires 5 args)
• Parameter range checks: Catches common mistakes like svf~ Q >= 1 or onepole~ frequency < 10 Hz
• Large patch warnings: Alerts when root patcher exceeds 80 objects
• Signal safety analysis: Detects feedback loops, high gain, unsafe comb~ feedback, and missing limiters before dac~

Quality of Life Improvements

• Auto-sizing: Objects and comments automatically fit their content
• Increased timeouts: Better handling of large patchers (5s vs 2s)
• Subpatcher support: Full navigation and creation within nested patchers
• Alias preservation: Encapsulate preserves user-facing names (*~ not times~, t not trigger)

Demo Videos

Understand: LLM Explaining a Max Patch

Video link. Acknowledgement: the patch being explained is from MaxMSP_TeachingSketches.

Generate: LLM Making an FM Synth

Full video with audio.

Installation

Prerequisites

• Python 3.8 or newer
• uv package manager
• Max 9 or newer (requires JavaScript V8 engine)

Installing the MCP Server

1. Install uv:

# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

1. Clone and set up:

git clone https://github.com/tiianhk/MaxMSP-MCP-Server.git
cd MaxMSP-MCP-Server
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

1. Connect to your MCP client:

For Claude Code (recommended):

As of Claude Code v2.1.47, MCP servers must be registered via the CLI (the mcpServers key in ~/.claude/settings.json is no longer read). Run:

claude mcp add --scope user maxmsp -- uv --directory /path/to/MaxMSP-MCP-Server run server.py

Verify with /mcp inside a Claude Code session.

Alternatively, for project-scoped configuration, create a .mcp.json at your project root:

{
  "mcpServers": {
    "maxmsp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/MaxMSP-MCP-Server",
        "run",
        "server.py"
      ]
    }
  }
}

For Claude Desktop or Cursor:

python install.py --client claude
# or
python install.py --client cursor

Installing to a Max Patch

1. Open MaxMSP_Agent/demo.maxpat in Max 9
2. Click script npm version to verify npm is installed
3. Click script npm install to install dependencies
4. Click script start to begin communication

Once connected, the LLM can explain, modify, or create Max objects within the patch.

Architecture

┌─────────────────┐     Socket.IO      ┌─────────────────┐
│   Claude Code   │ ←───────────────→  │    server.py    │
│  (MCP Client)   │     (port 5002)    │  (FastMCP/Python)│
└─────────────────┘                    └────────┬────────┘
                                                │
                                       ┌────────▼────────┐
                                       │ max_mcp_node.js │
                                       │   (Node.js)     │
                                       └────────┬────────┘
                                                │
                              ┌─────────────────┴─────────────────┐
                              │                                   │
                     ┌────────▼────────┐              ┌───────────▼───────────┐
                     │   max_mcp.js    │              │ max_mcp_v8_add_on.js  │
                     │  (Max js object)│              │   (Max v8 runtime)    │
                     └─────────────────┘              └───────────────────────┘

• server.py - Python FastMCP server with Socket.IO, validation, and tool definitions
• max_mcp_node.js - Node.js bridge running inside Max's node.script
• max_mcp.js - Main Max-side JavaScript handler for most operations
• max_mcp_v8_add_on.js - V8 JavaScript with boxtext access for encapsulation

MCP Tools Reference

Object Creation & Manipulation

Object Properties

Query Tools

Subpatcher Navigation

Safety & Organization

Development

After making code changes:

1. Reload js objects in Max (double-click to open editor, then close)
2. Restart node.script (script stop, then script start)

Acknowledgements

This fork is based on the original MaxMSP-MCP-Server created by Haokun Tian and Shuoyang Zheng.

The original project is licensed under the MIT License. See LICENSE for details.

Original repository: https://github.com/tiianhk/MaxMSP-MCP-Server

Disclaimer

This is a third-party implementation and not made by Cycling '74.