Suzu (鈴) - Claude Code Notification Server

# 🔔 Suzu (鈴) - Claude Code Notification Server A Model Context Protocol (MCP) server that plays your favorite Spotify tracks as notifications when Claude Code completes tasks. Named after the Japanese ceremonial bell, now with the power of music! 🎧 ## ✨ Features - 🎵 **Spotify integration** - Play your favorite tracks as notification sounds! 🎧 - 📱 **Desktop notifications** - Shows system notifications with custom messages - 🔊 **System sound notifications** - Native OS sounds as fallback - 🌍 **Cross-platform** - Works on macOS, Linux, and Windows - 🎶 **Multiple sound types** - Success, error, and info sounds (Spotify or system) - 🔧 **Debug logging** - Built-in debugging for troubleshooting - 🤖 **Automatic integration** - Works seamlessly with Claude Code ## 🚀 Quick Start ### ⚡ Super Easy Setup (Recommended) The fastest way to get Suzu with Spotify working is to let Claude do all the work: 1. **Ask Claude to set it up**: ``` fetch https://github.com/denar90/suzu-mcp/blob/main/SETUP.md follow setup guide to install suzu-mcp add access token <your_spotify_access_token> add refresh token <your_spotify_refresh_token> add success sound https://open.spotify.com/track/<your_track_id> ``` 2. **Get your Spotify tokens** from: https://suzu-mcp-spotify.netlify.app/ 3. **That's it!** Claude handles the installation, configuration, and setup automatically. ### Manual Installation 1. **Install from npm**: ```bash npm install -g suzu-mcp ``` 2. **Add to Claude Code**: ```bash claude mcp add suzu suzu ``` Or **install locally**: ```bash 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 ``` Or manually add to `~/.config/claude/claude_desktop_config.json`: ```json { "mcpServers": { "suzu": { "command": "suzu" } } } ``` 3. **Auto-approve notifications** (required for seamless experience): **Option 1 - One-time approval (Recommended)**: - When first prompted, select "Yes, and don't ask again for suzu commands" - This permanently approves suzu notifications without future prompts **Option 2 - Configuration file**: Add to `~/.config/claude/settings.json`: ```json { "enableAllProjectMcpServers": true } ``` **Option 3 - Tool-specific approval**: Add to your `~/.config/claude/claude_desktop_config.json`: ```json { "mcpServers": { "suzu": { "command": "suzu" } }, "toolUseConfirmation": { "suzu": "never" } } ``` 4. **Enable automatic notifications**: Create `~/CLAUDE.md` with: ```markdown # 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. ``` **Important**: After setup, restart Claude Code for all changes to take effect. ## 🎯 Usage ### Available Tools | Tool | Description | Parameters | |------|-------------|------------| | `task_completed` | Play success sound and show completion message | `message` (string), `sound_type` (success/error/info) | | `notify` | Show general notification with custom title | `title` (string), `message` (string), `sound_type` | | `test_sound` | Test notification sounds | `sound_type` (success/error/info) | | `show_config` | Display current configuration | None | | `configure_spotify_tokens` | Set up Spotify access and refresh tokens | `access_token` (string), `refresh_token` (optional), `refresh_endpoint` (optional) | | `configure_custom_sounds` | Set custom notification sounds | `source` (spotify/local), `sound_type` (success/error/info), `value` (track ID/file path) | ### Examples **Task completion:** ```javascript task_completed({ message: "Build completed successfully!", sound_type: "success" }) ``` **Custom notification:** ```javascript notify({ title: "Claude Code", message: "Ready to assist!", sound_type: "info" }) ``` **Testing sounds:** ```javascript test_sound({ sound_type: "success" }) ``` ### How It Works 1. **Automatic Integration**: When you have `~/CLAUDE.md` configured, Claude will automatically call `task_completed` when finishing tasks 2. **No Manual Calls**: You don't need to manually use the notification tools - Claude handles this automatically 3. **Task Completion Feedback**: Get audio and visual feedback when Claude finishes coding tasks, builds, deployments, etc. ## 🎵 Spotify Integration Transform your coding experience with custom music notifications! Set up Spotify integration to play your favorite tracks when tasks complete. ### Quick Setup with OAuth App 1. **Visit the Spotify OAuth App**: https://suzu-mcp-spotify.netlify.app/ 2. **Click "Login with Spotify"** to authorize the app 3. **Copy the tokens** shown after authorization 4. **Configure via Claude**: ``` Ask Claude: "Configure my Spotify with access_token: BQA... and refresh_token: AQC..." ``` Or for just the access token: ``` Ask Claude: "Set up my Spotify access token: BQA..." ``` ### Manual Setup (Advanced) If you prefer to create your own Spotify app: 1. **Create Spotify App**: - Go to https://developer.spotify.com/dashboard - Create new app with redirect URI: `http://localhost:8888/callback` - Note your Client ID and Client Secret 2. **Get Tokens**: - Use Spotify's Authorization Code flow - Or visit: https://developer.spotify.com/console/post-playlists/ - Get both access_token and refresh_token 3. **Configure Refresh Endpoint** (for auto-renewal): ``` Ask Claude: "Set up Spotify refresh endpoint: https://your-endpoint.com/refresh" ``` ### Setting Custom Sounds Once Spotify is configured, customize your notification sounds: ``` 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" ``` **Finding Spotify Track IDs:** 1. Right-click any song in Spotify 2. Share → Copy Song Link 3. Extract ID from URL: `https://open.spotify.com/track/TRACK_ID_HERE` 4. Use just the ID or the full URL - both work! ### Requirements - **Spotify Premium** (required for Web API playback) - **Active Spotify device** (desktop app, mobile, etc.) - Device must be playing or recently used ## 🔧 Platform Support ### macOS - Primary: `afplay` with system sounds (Glass, Sosumi, Ping) - Fallback: `say` command for spoken notifications - Tertiary: Terminal bell (`printf "\a"`) ### Linux - Primary: `paplay` for PulseAudio - Fallback: `aplay` for ALSA - Tertiary: Terminal bell ### Windows - Uses `rundll32 user32.dll,MessageBeep` ## 🐛 Troubleshooting ### Quick Test Use the built-in test command to verify everything works: ```bash # In Claude Code, run: test_sound({ sound_type: "success" }) ``` ### No sound playing? 1. **Check permissions**: Ensure audio permissions are granted to Claude Code 2. **Test manually**: Run `afplay /System/Library/Sounds/Glass.aiff` (macOS) in terminal 3. **Enable debug**: Run `claude --debug` and check console output for `[DEBUG]` messages 4. **Verify connection**: Type `/mcp` in Claude Code to see server status ### No automatic notifications? 1. **Check CLAUDE.md**: Ensure `~/CLAUDE.md` exists with the configuration above 2. **Restart Claude Code**: Configuration changes require a restart 3. **Check approvals**: Make sure you approved suzu tool usage (step 3 above) 4. **Test manually**: Try calling `task_completed` manually to verify it works ### MCP server not connecting? 1. **Check installation**: Run `suzu --version` in terminal 2. **Verify path**: For local installs, ensure the `dist/index.js` file exists 3. **Rebuild**: Run `npm run build` in the project directory 4. **Check config**: Verify `claude_desktop_config.json` syntax is valid JSON 5. **Restart**: Restart Claude Code after any config changes ### Debug output Look for these messages in `claude --debug`: ``` [DEBUG] Attempting to play sound: success on platform: darwin [DEBUG] Command 1 succeeded: afplay /System/Library/Sounds/Glass.aiff ``` ## 🛠️ Development ```bash # 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 ``` ## 📁 Project Structure ``` 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 ``` ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Test across platforms 5. Submit a pull request ## 📄 License MIT License - feel free to use and modify as needed. ## 🙏 Acknowledgments - Built with [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/servers) - Uses [node-notifier](https://github.com/mikaelbr/node-notifier) for desktop notifications - Inspired by the need for better task completion feedback in Claude Code