denar90/suzu-mcp

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

npm install -g suzu-mcp

2. Add to Claude Code:

claude mcp add suzu suzu

Or install locally:

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:

{
  "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:

   {
     "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:

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

Custom notification:

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

Testing sounds:

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:

# 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

# 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)
• Uses node-notifier for desktop notifications
• Inspired by the need for better task completion feedback in Claude Code