Suzu (鈴) - Claude Code Notification Server

🔔 Suzu-克劳德代码通知服务器

一个模型上下文协议（MCP）服务器，在Claude Code完成任务时播放您最喜欢的Spotify曲目作为通知。以日本礼仪钟命名，现在有音乐的力量！ 🎧

✨ 特性

• 🎵 Spotify集成 -播放您最喜欢的曲目作为通知声音！ 🎧
• 📱 桌面提醒 -显示带有自定义消息的系统通知
• 🔊 系统声音通知 -本机操作系统听起来像是回退
• 🌍 跨平台 -适用于macOS、Linux和Windows
• 🎶 多种声音类型 -成功、错误和信息声音（Spotify或系统）
• 🔧 调试记录 -用于故障排除的内置调试
• 🤖 自动集成 -与Claude Code无缝协作

🚀 快速开始

⚡ 超级简单的设置（推荐）

让Suzu和Spotify一起工作的最快方法是让Claude做所有的工作：

1. 请克劳德进行设置:

   fetch https://github.com/denar90/suzu-mcp/blob/main/SETUP.md
   follow setup guide to install suzu-mcp
   add access token 
   add refresh token 
   add success sound https://open.spotify.com/track/

1. 获取您的Spotify代币 发件人：https://suzu-mcp-spotify.netlify.app/

1. 就是这样！ Claude自动处理安装、配置和设置。

手动安装

1. 从npm安装:

npm install -g suzu-mcp

1. 添加到克劳德代码:

claude mcp add suzu suzu

或 本地安装:

git clone https://github.com/denar90/suzu-mcp.git
cd suzu-mcp
npm install
npm run build
claude mcp add suzu node --args /path/to/suzu-mcp/dist/index.js

或手动添加到 ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "suzu": {
      "command": "suzu"
    }
  }
}

1. 自动批准通知 （无缝体验所需）：

选项1-一次性批准（推荐）:

- 当第一次出现提示时，选择“是，不再询问suzu命令” - 这将永久批准suzu通知，而不会出现未来的提示

选项2-配置文件: 增添 ~/.config/claude/settings.json:

   {
     "enableAllProjectMcpServers": true
   }

选项3-工具特定批准: 添加到您的 ~/.config/claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "suzu": {
         "command": "suzu"
       }
     },
     "toolUseConfirmation": {
       "suzu": "never"
     }
   }

1. 启用自动通知:

创建 ~/CLAUDE.md 与：

   # Claude Code Configuration

   ## Default Behavior
   - Always call `task_completed` when finishing tasks if the suzu MCP server is available
   - Play completion notifications automatically without being asked
   - Use the suzu notification system for task completion feedback

   ## Instructions for Claude
   - When you complete any task, automatically check if the `task_completed` tool is available and call it with an appropriate completion message.

重要：安装后，重新启动Claude Code以使所有更改生效。

🎯 用法

可用工具

例子

任务完成：

task_completed({
  message: "Build completed successfully!",
  sound_type: "success"
})

自定义通知：

notify({
  title: "Claude Code",
  message: "Ready to assist!",
  sound_type: "info"
})

测试声音：

test_sound({
  sound_type: "success"
})

运作原理

1. 自动集成：当你有 ~/CLAUDE.md 配置后，Claude将自动调用 task_completed 完成任务时
2. 无手动呼叫：您不需要手动使用通知工具-Claude会自动处理此问题
3. 任务完成反馈：当Claude完成编码任务、构建、部署等时，获得音频和视觉反馈。

🎵 Spotify集成

使用自定义音乐通知改变您的编码体验！设置Spotify集成，以便在任务完成时播放您喜爱的曲目。

使用OAuth应用程序快速设置

1. 访问Spotify OAuth应用程序: https://suzu-mcp-spotify.netlify.app/

1. 点击“使用Spotify登录” 授权应用程序

1. 复制令牌 授权后显示

1. 通过Claude配置:

   Ask Claude: "Configure my Spotify with access_token: BQA... and refresh_token: AQC..."

或者仅针对访问令牌：

   Ask Claude: "Set up my Spotify access token: BQA..."

手动设置（高级）

如果您想创建自己的Spotify应用程序：

1. 创建Spotify应用程序:

- 首选https://developer.spotify.com/dashboard - 使用重定向URI创建新应用程序： http://localhost:8888/callback - 记下您的客户端ID和客户端密码

1. 获取代币:

- 使用Spotify的授权码流 - 或访问：https://developer.spotify.com/console/post-playlists/ - 同时获取access_token和refresh_token

1. 配置刷新端点 （用于自动续订）：

   Ask Claude: "Set up Spotify refresh endpoint: https://your-endpoint.com/refresh"

设置自定义声音

配置Spotify后，自定义您的通知声音：

Ask Claude: "Set my Spotify success sound to: 4uLU6hMCjMI75M1A2tKUQC"
Ask Claude: "Set my Spotify error sound to: https://open.spotify.com/track/60nZcImufyMA1MKQY3dcCH"
Ask Claude: "Set my Spotify info sound to: spotify:track:5QDLhrAOJJdNAmCTBusfHY"

查找Spotify曲目ID：

1. 右键单击Spotify中的任何歌曲
2. 分享→ 复制歌曲链接
3. 从URL提取ID： https://open.spotify.com/track/TRACK_ID_HERE
4. 只使用ID或完整的URL-两者都可以！

需求

• Spotify高级 （Web API播放需要）
• 活动Spotify设备 （桌面应用程序、移动设备等）
• 设备必须正在播放或最近使用过

🔧 平台支持

macOS

• 主要的，重要的 afplay 带有系统声音（Glass、Sosumi、Ping）
• 退路： say 语音通知命令
• 第三级：终端铃(printf "\a")

Linux

• 主要的，重要的 paplay PulseAudio
• 退路： aplay ALSA
• 第三级：终端铃

视窗

• 用途 rundll32 user32.dll,MessageBeep

🐛 故障排除

快速测试

使用内置的测试命令验证一切正常：

# In Claude Code, run:
test_sound({ sound_type: "success" })

没有声音播放？

1. 检查权限：确保向Claude Code授予音频权限
2. 手动测试：运行 afplay /System/Library/Sounds/Glass.aiff （macOS）在终端
3. 启用调试：运行 claude --debug 并检查控制台输出 [DEBUG] 消息
4. 验证连接：类型 /mcp 在Claude Code中查看服务器状态

没有自动通知？

1. 检查CLAUDE.md：确保 ~/CLAUDE.md 存在上述配置
2. 重新启动Claude代码：配置更改需要重新启动
3. 检查批准：确保您批准使用铃木工具（上述步骤3）
4. 手动测试：尝试拨打电话 task_completed 手动验证其是否有效

MCP服务器未连接？

1. 检查安装情况：运行 suzu --version 在终端
2. 验证路径：对于本地安装，请确保 dist/index.js 文件存在
3. 重建：运行 npm run build 在项目目录中
4. 检查配置：验证 claude_desktop_config.json 语法是有效的JSON
5. 重启：在任何配置更改后重新启动Claude Code

调试输出

在中查找这些消息 claude --debug:

[DEBUG] Attempting to play sound: success on platform: darwin
[DEBUG] Command 1 succeeded: afplay /System/Library/Sounds/Glass.aiff

🛠️ 发展

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Test the server directly
node dist/index.js

# Install with debugging
npm install --verbose

📁 项目结构

claude-notification-mcp/
├── src/
│   └── index.ts          # Main MCP server code
├── dist/                 # Built JavaScript files
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .mcp.json            # Local MCP configuration
└── README.md            # This file

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 跨平台测试
5. 提交拉取请求

📄 许可证

MIT许可证-可根据需要自由使用和修改。

🙏 致谢

• 内置于 模型上下文协议（MCP）
• 用途 节点通知器 用于桌面通知
• 受Claude Code中更好的任务完成反馈需求的启发