Suzu

Suzu MCP Server integrates with Claude Code to play Spotify tracks as task completion notifications. It provides desktop and system sounds across platforms and can be configured to automatically notify you when Claude Code finishes a task, using either Spotify-based sounds or native system sounds.

How to use

You use Suzu by connecting it to Claude Code as an MCP server. Once enabled, Claude Code will trigger notifications and sounds when tasks complete. You can run Suzu locally or install it globally and then register it with Claude Code so the server starts automatically with task completion.

How to install

Prerequisites you need before installing Suzu MCP Server: Node.js and npm are available on your system.

# Super easy setup (recommended) is handled automatically by Claude. No manual steps required here.

Manual installation options are shown below. Choose one of the following installation paths.

Option 1 — Install from npm globally

npm install -g suzu-mcp

Option 2 — Add Suzu to Claude Code (recommended path) and let Claude handle configuration

claude mcp add suzu suzu

Option 3 — Install locally and run from a built distribution

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

Option 4 — Manual Claude desktop config to register Suzu as an MCP server

{ "mcpServers": { "suzu": { "command": "suzu" } } }

Additional configuration and auto-approval

Auto-approve notifications to enable seamless operation. You have several options to approve Suzu tool usage so you won’t be prompted during normal use.

One-time approval (recommended) when prompted: select the option to remember this choice for Suzu commands.

Or configure global approval in Claude settings to enable automatic approvals for all project MCP servers.

Alternatively, set tool-specific approval in your Claude desktop configuration to never prompt for Suzu.

Enable automatic notifications

Create a Claude configuration file to enable automatic task completion notifications. When present, Claude will call the task_completed tool at the end of each task to play a sound and display a message.

# 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.

Usage examples

Task completion example showing how to trigger a completion sound and message.

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

General notification example with a custom title and message.

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

Spotify integration and sounds

Suzu can play Spotify tracks as notification sounds and provide separate sounds for success, error, and info. You configure Spotify access and choose the track IDs or URLs to use as notification sounds.

Platform support

Suzu supports macOS, Linux, and Windows. It uses platform-native methods to play sounds or provide desktop notifications and falls back to system sounds if needed.

Troubleshooting

If sound or notifications aren’t working, try the following steps: check audio permissions, test a manual system sound, enable debugging, and verify that Suzu is connected as an MCP server.

# Quick test from Claude Code
test_sound({ sound_type: "success" })

If automatic notifications aren’t firing, verify the Claude configuration file exists and is loaded, restart Claude Code, and confirm tool approvals are in place.

Development and project structure

During development you can run in development mode, build for production, and test the server directly.

# 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 configuration snippet

{
  "mcpServers": {
    "suzu": {
      "command": "suzu"
    }
  }
}

Starting the server from a local build

If you built Suzu locally, start it using Node and the built index file.

node /path/to/suzu-mcp/dist/index.js

Another startup option from a local install

If you installed Suzu locally and want Claude to launch it, register the runtime as shown.

claude mcp add suzu node --args /path/to/suzu-mcp/dist/index.js

Available tools

task_completed

Play a success/error/info sound and show a completion message when Claude finishes a task

notify

Show a general notification with a custom title and message, optionally with a sound type

test_sound

Test the available notification sounds for quick verification

show_config

Display the current MCP server configuration to verify active settings

configure_spotify_tokens

Set up Spotify access and refresh tokens used for Spotify-based sounds

configure_custom_sounds

Set custom sounds for different notification types such as success, error, and info