Notification Sound MCP

🔔 Play a sound when the task is finished so you know when to continue creating wonderful things 🔔

A Model Context Protocol (MCP) server that provides notification sound functionality. This server allows MCP clients like Claude Code to play audio notifications, helping you stay aware of task completion without constantly monitoring your screen.

Use Case

If you want to get a notification after a task is completed, you can use the following prompt:

calculate 2 + 2, then play sound.

add unit test for this module. after that play notification.

Features

• Cross-platform support: Works on macOS, Linux, and Windows
• Zero configuration: Works out of the box with automatic audio player detection
• Audio format support: Supports MP3 and WAV files

Usage with MCP Clients

VSCode with GitHub Copilot Chat

To use this MCP server with VSCode and GitHub Copilot Chat, add the server configuration to your VSCode settings:

{
  "mcp.servers": {
    "notification-sound": {
      "command": "npx",
      "args": ["-y", "notification-sound-mcp"],
      "env": {}
    }
  }
}

Claude Code and Claude Desktop

Add this server to your Claude Code configuration:

1. Open Claude Code settings
2. Add the MCP server configuration:

{
  "mcpServers": {
    "notification-sound": {
      "command": "npx",
      "args": ["-y", "notification-sound-mcp"]
    }
  }
}

3. Restart Claude Code
4. The play_notification_sound tool will be available for use

Or if you want to add it with a command:

claude mcp add notification-sound-mcp -s user -- npx -y notification-sound-mcp

Cursor IDE

To integrate with Cursor IDE:

1. Open Cursor settings
2. Navigate to the MCP servers section
3. Add a new server configuration:

{
  "notification-sound": {
    "command": "npx",
    "args": ["-y", "notification-sound-mcp"]
  }
}

4. Restart Cursor IDE
5. Access the tool through Cursor's AI chat

Generic MCP Client Configuration

For any MCP-compatible client, use this general configuration pattern:

{
  "servers": {
    "notification-sound": {
      "command": "npx",
      "args": ["-y", "notification-sound-mcp"]
    }
  }
}

Supported Audio Players

The server automatically detects and uses the first available audio player based on your operating system:

macOS

• afplay (built-in)

Linux

• ffplay (FFmpeg)
• mpv
• paplay (PulseAudio)
• aplay (ALSA)
• play (SoX)

Windows

• ffplay (FFmpeg)
• powershell (built-in)
• mpv

API Reference

Tools

play_notification_sound

Plays a notification sound

Parameters: None

Returns:

• Success: { content: [{ type: "text", text: "Notification sound played!" }] }
• Error: { content: [{ type: "text", text: "Error message" }], isError: true }

Common Error Messages:

• "No supported audio player found. Please install ffplay, paplay, aplay, play, or mpv."
• "Audio player does not support the sound file format."
• "Failed to play notification sound: [specific error]"

Requirements

• Node.js: Version 18 or higher
• Audio player: At least one supported audio player must be installed on your system

Testing

Test the notification functionality locally:

# Test notification sound playback
npx notification-sound-mcp --test-notification

Troubleshooting

No Sound Playing

1. Check audio player availability:

   # Linux/macOS - check if common players are installed
   which ffplay mpv paplay aplay play
   
   # Windows - check if ffplay is available
   where ffplay

2. Install an audio player:

   # Ubuntu/Debian
   sudo apt install ffmpeg  # provides ffplay
   
   # macOS (afplay is built-in, but you can also install others)
   brew install ffmpeg mpv
   
   # Windows - install FFmpeg or mpv

MCP Integration Issues

1. Server not starting: Check Node.js version (requires 18+)
2. Tool not available: Verify MCP client configuration points to correct path
3. Permission errors: Ensure the server has permission to execute audio commands

Development

To modify the notification sound, replace assets/notification.mp3 with your preferred audio file (MP3 or WAV format).

To add support for additional audio players, modify the audioPlayers configuration in src/audio_player.js.