suzu-mcp

denar90/suzu-mcp

3.2

If you are the rightful owner of suzu-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Suzu (鈓) is a Model Context Protocol (MCP) server designed to provide gentle chime notifications and desktop alerts for task completion in Claude Code.

Tools
  1. task_completed

    Play success sound and show completion message

  2. notify

    Show general notification with custom title

šŸ”” Suzu (鈓) - Claude Code Notification Server

A Model Context Protocol (MCP) server that provides gentle chime notifications and desktop alerts for Claude Code task completion. Named after the Japanese ceremonial bell.

✨ Features

  • šŸ”Š System sound notifications - Plays native OS sounds when tasks complete
  • šŸ“± Desktop notifications - Shows system notifications with custom messages
  • šŸŒ Cross-platform - Works on macOS, Linux, and Windows
  • šŸŽµ Multiple sound types - Success, error, and info sounds
  • šŸ”§ Debug logging - Built-in debugging for troubleshooting
  • šŸ¤– Automatic integration - Works seamlessly with Claude Code

šŸš€ Quick Start

Installation

  1. Install from npm:
npm install -g suzu-mcp
  1. 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"
    }
  }
}
  1. 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"
      }
    }
    
  2. 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 gentle bell sounds for task completion feedback
    

    Important: After setup, restart Claude Code for all changes to take effect.

šŸŽÆ Usage

Available Tools

ToolDescriptionParameters
task_completedPlay success sound and show completion messagemessage (string), sound_type (success/error/info)
notifyShow general notification with custom titletitle (string), message (string), sound_type

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"
})

šŸ”§ 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

No sound playing?

  1. Check permissions: Ensure audio permissions are granted
  2. Test manually: Run afplay /System/Library/Sounds/Glass.aiff (macOS)
  3. Enable debug: Run claude --debug and check console output
  4. Verify connection: Check /mcp in Claude Code for server status

MCP server not connecting?

  1. Check path: Ensure the dist/index.js file exists
  2. Rebuild: Run npm run build
  3. Check config: Verify claude_desktop_config.json syntax
  4. Restart: Restart Claude Code after 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