🚀 🔊 MCP Make Sound
MCP Make Sound 是一个基于模型上下文协议（MCP）的服务器，专为 macOS 系统打造，具备全面的声音播放功能。它允许 AI 助手及其他 MCP 客户端播放系统声音、进行文本转语音，还能播放自定义音频文件，为用户带来丰富的音频反馈体验。
🚀 快速开始
运行服务器
启动 MCP 服务器：
npm start
若要在开发环境中实现自动重新加载：
npm run dev
✨ 主要特性
- 🔔 简单声音方法：预配置了信息、警告和错误提示音。
- 🎵 自定义系统声音：可播放 14 种内置的 macOS 系统声音。
- 🗣️ 文本转语音：能将文本转换为语音，且支持自定义语音。
- 📁 文件播放：可播放磁盘上的自定义音频文件。
- 🚀 基于 TypeScript 和 MCP SDK 构建。
- 🪶 轻量级设计，易于集成。
📦 安装指南
- 克隆此仓库：
git clone
cd mcp-make-sound
- 安装依赖项：
npm install
- 构建项目：
npm run build
💻 使用示例
基础用法
示例：Claude 与 Warp 终端集成
以下是如何设置 MCP 声音服务器，以便在 Warp 终端中 AI 任务完成时提供音频反馈：
配置规则：“当 AI 任务完成时，使用 mcp - make - sound 播放声音。MCP 支持错误、信息和成功三种状态。根据 AI 任务的结果播放相应的声音。”
通过此设置，你可以：
- 🔔 当任务成功完成时，听到悦耳的提示音。
- ⚠️ 当出现警告或部分完成时，收到警报声。
- ❌ 当出现错误或失败时，获得清晰的音频反馈。
音频反馈能让你在专注于其他工作的同时，第一时间知晓 AI 助手何时完成请求处理。
高级用法
可用工具
服务器提供了四种工具：
简单声音方法（旧版）
play_info_sound- 描述：播放信息类系统声音。
- 参数：无。
- 声音：Glass.aiff
play_warning_sound- 描述：播放警告类系统声音。
- 参数：无。
- 声音：Purr.aiff
play_error_sound- 描述：播放错误类系统声音。
- 参数：无。
- 声音：Sosumi.aiff
高级声音方法
play_sound- 描述：可通过自定义参数播放各种类型的声音。
- 参数：
type（必需）："system"、"tts"或"file"。- 根据类型的不同还有其他附加参数（见以下示例）。
系统声音
播放 14 种内置的 macOS 系统声音：
{
"name": "play_sound",
"arguments": {
"type": "system",
"name": "Basso"
}
}
可用的系统声音：
Basso、Blow、Bottle、Frog、Funk、Glass、Hero、Morse、Ping、Pop、Purr、Sosumi、Submarine、Tink
文本转语音
将文本转换为语音，并可选择语音：
{
"name": "play_sound",
"arguments": {
"type": "tts",
"text": "Hello, this is a test message",
"voice": "Albert"
}
}
不指定语音（使用系统默认语音）：
{
"name": "play_sound",
"arguments": {
"type": "tts",
"text": "Task completed successfully"
}
}
支持的语音：
- 英语：
Albert、Alice、Bad News、Bahh、Bells、Boing、Bruce、Bubbles、Cellos、Daniel、Deranged、Fred、Good News、Hysterical、Junior、Kathy、Pipe Organ、Princess、Ralph、Trinoids、Whisper、Zarvox - 国际语音：
Anna、Amélie、Daria、Eddy、Fiona、Jorge、Juan、Luca、Marie、Moira、Nora、Rishi、Samantha、Serena、Tessa、Thomas、Veena、Victoria、Xander、Yelda、Zosia
注意：如果指定了不支持的语音，系统将自动回退到默认语音并继续播放。
自定义音频文件
播放磁盘上的音频文件：
{
"name": "play_sound",
"arguments": {
"type": "file",
"path": "/Users/username/Music/notification.mp3"
}
}
支持常见的音频格式：.aiff、.wav、.mp3、.m4a 等。
🔒 安全与限制
- 系统声音：仅允许使用 14 种官方的 macOS 系统声音。
- 文本转语音：
- 文本最大限制为 1000 个字符。
- 支持语音验证，若指定不支持的语音，将优雅地回退到系统默认语音。
- 为确保安全，精心筛选了 43 种以上支持的语音。
- 文件播放：需要绝对路径，并验证文件是否存在。
🔗 与 MCP 客户端集成
此服务器可与任何兼容 MCP 的客户端集成，例如：
- 🤖 Claude Desktop
- 🛠️ 自定义 MCP 客户端
- 🧠 支持 MCP 的 AI 助手
MCP 配置示例
将以下内容添加到你的 MCP 客户端配置中：
{
"mcp-make-sound": {
"command": "node",
"args": [
"/Users/nocoo/Workspace/mcp-make-sound/dist/index.js"
],
"env": {},
"working_directory": "/Users/nocoo/Workspace/mcp-make-sound",
"start_on_launch": true
}
}
示例工具调用：
{
"name": "play_info_sound",
"arguments": {}
}
{
"name": "play_sound",
"arguments": {
"type": "system",
"name": "Hero"
}
}
📚 详细文档
项目结构
mcp-make-sound/
├── src/
│ ├── index.ts # 主服务器实现
│ └── __tests__/ # 单元测试
│ └── sound.test.ts # 声音系统测试
├── dist/ # 编译后的 JavaScript 输出
├── eslint.config.js # ESLint 配置
├── vitest.config.ts # Vitest 测试配置
├── package.json # 项目配置
├── tsconfig.json # TypeScript 配置
└── README.md # 本文件
脚本
构建与运行
npm run build- 🔨 将 TypeScript 编译为 JavaScript。npm start- ▶️ 运行编译后的服务器。npm run dev- 🔄 开发模式，支持自动重新构建和重启。npm run kill- 🛑 停止所有正在运行的 MCP 服务器实例。
代码质量与测试
npm run lint- 🔍 检查代码风格和错误。npm run lint:fix- 🔧 修复可自动修复的代码风格问题。npm run test- 🧪 在监视模式下运行测试。npm run test:run- ✅ 运行一次测试。npm run test:ui- 🎛️ 以交互式 UI 运行测试。
工作原理
- 服务器使用官方 SDK 实现 MCP 协议。
- 它提供了四种工具，用于实现不同的声音功能。
- 当调用工具时，它会使用 macOS 命令：
afplay用于播放音频文件（系统声音和自定义文件）。say用于文本转语音合成。
- 系统声音位于
/System/Library/Sounds/。 - 服务器通过标准输入输出（stdio）进行通信。
🔧 技术细节
- 🔌 传输方式：标准输入输出（stdio）
- 📡 协议：模型上下文协议（MCP）
- 🎧 音频后端：macOS 的
afplay和say命令 - 🎵 声音文件：系统 .aiff 文件、自定义音频文件和合成语音
🚨 错误处理
服务器包含全面的错误处理机制：
- 验证工具名称和参数。
- 处理
afplay和say命令失败的情况。 - 验证每种声音类型所需的参数。
- 向客户端返回适当的错误消息。
- 在出现错误时优雅地关闭服务器。
📄 许可证
本项目采用 MIT 许可证。
🤝 贡献
欢迎贡献代码！请随时提交拉取请求。
🎼 声音功能
简单方法（旧版）
- 🔔 信息：Glass.aiff - 悦耳的提示音。
- ⚠️ 警告：Purr.aiff - 温和的警报声。
- ❌ 错误：Sosumi.aiff - 独特的错误提示音。
高级方法（play_sound）
- 🎵 14 种系统声音：所有内置的 macOS 系统声音均可使用。
- 🗣️ 50 多种文本转语音语音：支持多种语言和角色语音。
- 📁 自定义文件：支持 .aiff、.wav、.mp3、.m4a 等多种音频格式。
这些功能为任何应用需求提供了丰富的音频反馈选项。