denar90/suzu-mcp
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.
task_completed
Play success sound and show completion message
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
- Install from npm:
npm install -g suzu-mcp
- 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"
}
}
}
-
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" } }
-
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
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 |
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?
- Check permissions: Ensure audio permissions are granted
- Test manually: Run
afplay /System/Library/Sounds/Glass.aiff
(macOS) - Enable debug: Run
claude --debug
and check console output - Verify connection: Check
/mcp
in Claude Code for server status
MCP server not connecting?
- Check path: Ensure the
dist/index.js
file exists - Rebuild: Run
npm run build
- Check config: Verify
claude_desktop_config.json
syntax - 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
- Fork the repository
- Create a feature branch
- Make your changes
- Test across platforms
- 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