maxmcp

MaxMCP - Native MCP Server for Max/MSP

Control your Max/MSP patches with Claude Code using natural language.

Overview

MaxMCP is a native C++ external object for Max/MSP that acts as an MCP (Model Context Protocol) server. It enables Claude Code to control Max/MSP patches through natural language commands, with zero configuration required from users.

Key Features

• ✅ Zero configuration: Just place [maxmcp] in your patch
• ✅ Automatic patch detection: Auto-generated patch IDs
• ✅ Natural language control: "Add a 440Hz oscillator to synth patch"
• ✅ Multi-patch support: Control multiple patches simultaneously
• ✅ Complete MCP toolset: 26 tools for comprehensive patch control
• ✅ Auto-cleanup: Lifecycle management on patch close

Architecture

Claude Code (MCP Client)
    ↕ stdio (JSON-RPC)
Node.js Bridge (websocket-mcp-bridge.js)
    ↕ WebSocket
[maxmcp] C++ External Object
    ↕ Max API
Max/MSP Patches

Components:

• maxmcp.mxo: Single unified external with two modes:
  • @mode agent: WebSocket server, MCP protocol handler (1 per Max instance)
  • @mode patch: Patch registration (1 per controllable patch, default)
• Bridge: stdio ↔ WebSocket translator (Node.js, launched automatically)

Tech Stack

• Language: C/C++ (Max SDK 8.6+)
• Build System: CMake 3.19+
• Architecture: arm64 (Apple Silicon native)
• MCP Protocol: stdio-based JSON-RPC
• JSON Library: nlohmann/json 3.11.0+
• WebSocket: libwebsockets (installed via Homebrew, bundled into .mxo at build time)
• TLS: OpenSSL 3.x (installed via Homebrew, bundled into .mxo at build time)
• Code Signing: Ad-hoc signature (auto-applied)
• Distribution: Max Package

Installation

Option 1: Max Package Manager (Coming Soon)

1. Open Max/MSP
2. File → Show Package Manager
3. Search "MaxMCP"
4. Click Install

Option 2: Manual Install

1. Download latest release
2. Extract to ~/Documents/Max 9/Packages/
3. Restart Max

Option 3: Build from Source (Development Setup)

Use this path if you're cloning the repository and want to build the external yourself.

1. Clone the repo

   git clone https://github.com/signalcompose/MaxMCP.git
   cd MaxMCP
   

2. Install prerequisites

   brew install cmake nlohmann-json libwebsockets openssl
   

   • Requires macOS 13+, Xcode Command Line Tools, Max 9.1+, Node.js 18+ with npm.
3. Fetch the Max SDK with submodules

   git clone https://github.com/Cycling74/max-sdk.git --recursive max-sdk
   

   The --recursive flag is critical; without it max-pretarget.cmake is missing.
4. Install bridge dependencies

   cd package/MaxMCP/support/bridge
   npm install
   cd ../../../..
   

   This installs the ws dependency used by websocket-mcp-bridge.js.
5. Build the external

   ./build.sh --clean Release   # optional but recommended for first build
   ./build.sh Release
   

   The script configures CMake, builds the external, and installs maxmcp.mxo into package/MaxMCP/externals/. Confirm the bundle exists:

   ls package/MaxMCP/externals/maxmcp.mxo/Contents/MacOS/maxmcp
   

6. Deploy to Max 9 Packages

   ./deploy.sh
   

   This copies package/MaxMCP to ~/Documents/Max 9/Packages/MaxMCP.
7. (Optional) Manual CMake invocation

   cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
   cmake --build build
   cmake --install build --prefix package/MaxMCP
   

8. Verify bridge tooling

   cd package/MaxMCP/support/bridge
   npm test   # runs Jest suite against websocket-mcp-bridge.js
   

Quick Start

1. Open Help Patch

In Max/MSP:

• Help → MaxMCP Package → 00-index.maxpat

Or manually:

open ~/Documents/Max\ 9/Packages/MaxMCP/examples/00-index.maxpat

2. Start MCP Agent & Bridge

Option A (recommended): In 00-index.maxpat, click the "START" message to launch the agent and bridge automatically.

Option B (manual patch):

1. Unlock a new patcher (Cmd+E) and add:

   [maxmcp @mode agent @port 7400]
   

2. Add a message box with START and connect it to the agent inlet.
3. Click the START message. The Max Console should log:

   WebSocket server started on port 7400
   maxmcp: maxmcp (agent mode) started on port 7400
   

4. Start the Node bridge in a terminal:

   node ~/Documents/Max\ 9/Packages/MaxMCP/support/bridge/websocket-mcp-bridge.js ws://localhost:7400
   

   Run npm install inside package/MaxMCP/support/bridge/ first if you have not already.

3. Configure Claude Code

Run this command in your terminal:

claude mcp add maxmcp node ~/Documents/Max\ 9/Packages/MaxMCP/support/bridge/websocket-mcp-bridge.js ws://localhost:7400