用Claude代码自然语言控制你的Max/MSP补丁。

概述

MaxMCP 是 Max/MSP 的原生 C++ 外部对象，作为 MCP（模型上下文协议）服务器。它使 Claude Code 能够通过自然语言命令控制 Max/MSP 补丁，用户无需进行任何配置。

主要特色

• ✅ 零配置：只需在你的补丁中放置[maxmcp]
• ✅ 自动补丁检测：自动生成补丁ID
• ✅ 自然语言控制：“在合成器音色中添加440Hz振荡器”
• ✅ 多补丁支持：同时控制多个补丁
• ✅ 完整MCP工具集：30个全面补丁控制工具
• ✅ 自动清理：补丁关闭时的生命周期管理

建筑

组成部分：

• maxmcp.mxo：单一统一外置，有两种模式：
• @mode agent：WebSocket服务器，MCP协议处理器（每个Max实例1个）
• @mode patch：补丁注册（每个可控补丁1个，默认）
• 桥接器：标准↔ WebSocket翻译器（Node.js，自动启动）

技术堆栈

• 语言：C/C++（Max SDK v8.2.0）
• 构建系统：CMake 3.19+
• 架构：arm64（苹果硅原生）

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: 30 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 v8.2.0)
• 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 --branch v8.2.0 https://github.com/Cycling74/max-sdk.git --recursive max-sdk
   

   The --recursive flag is critical; without it max-pretarget.cmake is missing. v8.2.0 is pinned because newer max-sdk no longer ships the max-sdk-base submodule (it switched to CMake FetchContent).
4. Install bridge dependencies