MaxMCP-用于Max/MSP的本机MCP服务器
使用自然语言使用Claude Code控制您的Max/MSP补丁。
概述
MaxMCP是Max/MSP的原生C++外部对象，充当MCP（模型上下文协议）服务器。它使Claude Code能够通过自然语言命令控制Max/MSP补丁，用户无需进行任何配置。
主要特点
- ✅ 零配置：只是地点
[maxmcp]在你的补丁 - ✅ 自动补丁检测：自动生成的补丁ID
- ✅ 自然语言控制：“在合成器补丁中添加一个440Hz振荡器”
- ✅ 多补丁支持：同时控制多个补丁
- ✅ 完整的MCP工具集：26个全面补丁控制工具
- ✅ 自动清理：补丁关闭时的生命周期管理
建筑
Claude Code (MCP Client)
↕ stdio (JSON-RPC)
Node.js Bridge (websocket-mcp-bridge.js)
↕ WebSocket
[maxmcp] C++ External Object
↕ Max API
Max/MSP Patches组件:
- maxmcp.mxo：单个统一外部，有两种模式：
- @mode agent：WebSocket服务器，MCP协议处理程序（每个Max实例1个） - @mode patch：补丁注册（每个可控补丁1个，默认）
- 桥：stdio↔ WebSocket转换器（Node.js，自动启动）
技术栈
- 语言：C/C++（最大SDK 8.6+）
- 构建系统：CMake 3.19+
- 建筑：arm64（苹果硅原生）
- MCP协议：基于stdio的JSON-RPC
- JSON库：nlohmann/json 3.11.0+
- WebSocket：libwebsockets（通过Homebrew安装，在构建时捆绑到.mxo中）
- 传输层安全：OpenSSL 3.x（通过Homebrew安装，在构建时捆绑到.mxo中）
- 代码签名：临时签名（自动应用）
- 分布：最大包装
安装
选项1:Max包管理器（即将推出）
- 打开Max/MSP
- File → 显示包管理器
- 搜索“MaxMCP”
- 点击安装
选项2：手动安装
- 下载最新版本
- 提取到
~/Documents/Max 9/Packages/ - 重新启动Max
选项3：从源代码构建（开发设置）
如果要克隆存储库并希望自己构建外部存储库，请使用此路径。
- 克隆仓库
git clone https://github.com/signalcompose/MaxMCP.git
cd MaxMCP- 安装必备组件
brew install cmake nlohmann-json libwebsockets openssl- 需要macOS 13+、Xcode命令行工具、Max 9.1+、带npm的Node.js 18+。
- 使用子模块获取Max SDK
git clone https://github.com/Cycling74/max-sdk.git --recursive max-sdk这 --recursive 旗帜至关重要；没有它 max-pretarget.cmake 不见了。
- 安装网桥依赖项
cd package/MaxMCP/support/bridge
npm install
cd ../../../..这将安装 ws 依赖关系由使用 websocket-mcp-bridge.js.
- 构建外部
./build.sh --clean Release # optional but recommended for first build
./build.sh Release该脚本配置CMake，构建外部，并安装 maxmcp.mxo 进入 package/MaxMCP/externals/.确认捆绑包存在：
ls package/MaxMCP/externals/maxmcp.mxo/Contents/MacOS/maxmcp- 最多部署9个包
./deploy.sh此副本 package/MaxMCP 到 ~/Documents/Max 9/Packages/MaxMCP.
- （可选）手动CMake调用
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build --prefix package/MaxMCP- 验证桥接工具
cd package/MaxMCP/support/bridge
npm test # runs Jest suite against websocket-mcp-bridge.js快速开始
1.打开帮助补丁
在Max/MSP中：
- Help → MaxMCP封装→
00-index.maxpat
或手动：
open ~/Documents/Max\ 9/Packages/MaxMCP/examples/00-index.maxpat2.启动MCP代理和网桥
选项A（推荐）： 在 00-index.maxpat，单击“START”消息自动启动代理和网桥。
选项B（手动补丁）：
- 解锁新的修补程序（Cmd+E）并添加：
[maxmcp @mode agent @port 7400]- 添加一个消息框
START并将其连接到试剂入口。 - 点击
START消息。Max控制台应记录：
WebSocket server started on port 7400
maxmcp: maxmcp (agent mode) started on port 7400- 在终端中启动Node网桥：
node ~/Documents/Max\ 9/Packages/MaxMCP/support/bridge/websocket-mcp-bridge.js ws://localhost:7400跑 npm install 里面 package/MaxMCP/support/bridge/ 首先，如果你还没有。
3.配置克劳德代码
在终端中运行以下命令：
claude mcp add maxmcp node ~/Documents/Max\ 9/Packages/MaxMCP/support/bridge/websocket-mcp-bridge.js ws://localhost:7400重新启动Claude Code以应用更改。
4.创建可控补丁
在Max补丁中，添加：
[maxmcp @alias my-synth @group synth]属性：
@mode patch-客户端模式（默认，可以省略）@alias my-synth-自定义补丁ID（可选，如果省略则自动生成）@group synth-用于筛选的组名（可选）
5.用自然语言控制
在克劳德代码中，说：
- “列出所有活动的Max补丁”
- “在我的合成器补丁中添加一个440Hz振荡器”
- “将振荡器连接到dac~”
- “显示Max控制台日志”
可用的MCP工具
MaxMCP提供6个类别的26个工具：
| 类别 | 计数 | 工具 |
|---|---|---|
| 补丁管理 | 3 | list_active_patches, get_patch_info, get_frontmost_patch |
| 对象操作 | 12 | add_max_object, remove_max_object, get_objects_in_patch, set_object_attribute, get_object_attribute, get_object_value, get_object_io_info, get_object_hidden, set_object_hidden, redraw_object, replace_object_text, assign_varnames |
| 连接操作 | 4 | connect_max_objects, disconnect_max_objects, get_patchlines, set_patchline_midpoints |
| 补丁状态 | 3 | get_patch_lock_state, set_patch_lock_state, get_patch_dirty |
| 层次结构 | 2 | get_parent_patcher, get_subpatchers |
| 公用事业 | 2 | get_console_log, get_avoid_rect_position |
看 docs/mcp-tools-reference.md 获取完整的参数和响应文档。
开发状态
当前版本：v1.1.0✅
✅ 完成:
- 阶段1：核心外部对象，WebSocket服务器
- 第二阶段：完整的MCP工具集、E2E测试、Max Package集成
- 第一阶段基础设施：CI/CD管道、综合测试（117次测试）、代码质量自动化
🔄 下一步:
- 第3阶段：最大包管理器提交
- 第4阶段：跨平台构建（Windows/Intel支持）
看 更改日志.md 版本历史和 docs/ 了解详细的规格和开发路线图。
文档
Claude代码插件
MaxMCP为Max/MSP开发提供了一个具有四种技能的Claude Code插件。
安装
/plugin marketplace add signalcompose/maxmcp
/plugin install maxmcp@maxmcp可用技能
补丁指南
创建组织良好的Max补丁的指南：
/maxmcp:patch-guidelines提供：
- 对象定位的布局规则
- 变量名命名约定
- JavaScript（v8/v8ui）最佳实践
- MCP工具快速参考
最大技术
Max/MSP实施技术和最佳实践：
/maxmcp:max-techniques提供：
- poly~&batcher架构模式
- pattr/patrstorage参数管理
- 恒定参数安全，采样率处理
m4l技术
Max for Live开发技术和最佳实践：
/maxmcp:m4l-techniques提供：
- 活动对象模型（路径→ id → live.object→ 现场观测者）
- 设备命名空间(
---对比#0)以及pattr持久性 - 控制器映射、dBFS参考、Push2自动映射
最大资源
访问Max.app内置文档和示例：
/maxmcp:max-resources提供：
- 对象参考页面（入口、出口、方法、属性）
- Max.app中的示例补丁
- 代码片段
- Max文档的全文搜索
示例补丁
该软件包包括全面的示例补丁 examples/:
- 00-index.maxpat -主帮助/索引（也可通过右键单击获得→ “打开maxmcp帮助”）
- 01-基本调节最大值 -基本补丁注册
- 01-claude-code连接.maxpat -克劳德代码E2E连接测试
- 02-海关联络员.maxpat -自定义别名使用
- 03-团体签名.maxpat -组筛选
- **04-05-06多补丁-\*.maxpat** -多补丁场景（synth1、synth2、fx1）
- 07-mcp-tools-test.maxpat -MCP工具测试
故障排除
代理无法启动
- 检查端口7400是否可用：
lsof -i :7400 - 如果桥记录
ECONNREFUSED，开始[maxmcp @mode agent @port 7400]然后单击START - 检查Max控制台是否有错误消息
Claude Code无法连接
- 验证网桥是否正在运行：检查Max控制台是否有“网桥已启动”消息
- 之后重新启动Claude代码
claude mcp add命令 - 检查MCP配置
claude mcp list - 运行网桥并调试以捕获WebSocket错误：
DEBUG=1 node ~/Documents/Max\ 9/Packages/MaxMCP/support/bridge/websocket-mcp-bridge.js ws://localhost:7400
对象未出现
- 确保补丁已解锁（Cmd+E）
- 检查补丁是否
[maxmcp]对象已注册 - 验证补丁ID:使用
list_active_patches工具
许可证
MaxMCP根据 信号合成公平贸易许可v1.0。参见 许可证 获取完整的许可证文本。
第三方许可证
MaxMCP使用开源库。看 第三阶段_许可.md 获取完整的归属和许可证详细信息。
开发与测试
MaxMCP使用全面的CI/CD管道，具有自动测试和代码质量检查功能：
- 测试：117个单元测试（谷歌测试1.17.0），通过率100%
- CI/CD：用于自动化测试和linting的GitHub Actions工作流
- 代码质量：使用clang-format、ESLint和自动化测试的预提交挂钩
- 本地设置:
npm install通过Husky启用预提交挂钩
看 docs/PHASE1_基础设施.md 有关测试基础架构的详细信息。
贡献
我们欢迎社区的贡献！请参阅：
- 贡献.md -如何做出贡献
- 代码_OF_CONDUCT.md -社区指南
- 安全.md -安全策略
此项目使用 克劳德代码 为了发展。看 CLAUDE.md AI助手指南和项目惯例。
所有贡献都由CI自动验证，以确保代码质量和测试覆盖率。
作者
山本弘
支持
- GitHub问题：https://github.com/signalcompose/MaxMCP/issues
- 文件：见
docs/目录 - 安全：请参阅 安全.md 用于漏洞报告
灵感
这个项目的灵感来自 MaxMSP MCP服务器多副本，用本机C++架构重新构想，以提高性能和Max集成。