🔔 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:

2. Add to Claude Code:

Or install locally:

Or manually add to ~/.config/claude/claude_desktop_config.json:

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:

   { "enableAllProjectMcpServers": true }

   Option 3 - Tool-specific approval: Add to your ~/.config/claude/claude_desktop_config.json:

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

4. Enable automatic notifications: Create ~/CLAUDE.md with:

   # 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

Examples

Task completion:

Custom notification:

Testing sounds:

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:

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:

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:

🛠️ Development

📁 Project Structure

🤝 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)

• Uses node-notifier for desktop notifications

• Inspired by the need for better task completion feedback in Claude Code