Desktop Notification MCP Server

A Model Context Protocol (MCP) server that enables AI agents to send cross-platform desktop notifications with priority levels, categories, and duration control.

Features

• Cross-platform support (macOS, Windows, Linux)
• Priority levels for urgency control
• Category-based visual distinction
• Configurable display duration
• Optional notification sounds
• Success/error status reporting

Installation

npm install
npm run build

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "desktop-notifications": {
      "command": "node",
      "args": [
        "/absolute/path/to/desktop-notification-mcp/dist/index.js"
      ]
    }
  }
}

Parameters

Parameter	Type	Default	Description
title	string	required	Notification title
message	string	required	Notification message body
sound	boolean	false	Enable notification sound
priority	string	"normal"	Priority level: "low", "normal", "high", "critical"
category	string	"task"	Category: "task", "error", "success", "progress", "question", "reminder"
duration	number	auto	Display duration in milliseconds (0 = persistent)

Priority Levels

• low - Quick updates, 5 second timeout
• normal - Standard notifications, 10 second timeout (default)
• high - Important updates, 15 second timeout
• critical - Critical alerts, persistent until dismissed

Categories

• task - General task notifications
• error - Error and failure notifications
• success - Success and completion notifications
• progress - Progress updates
• question - Questions requiring user attention
• reminder - Reminders and scheduled notifications

Examples

Basic Notification

{
  "title": "Task Complete",
  "message": "Your analysis has finished"
}

High Priority Error

{
  "title": "Build Failed",
  "message": "Tests failed - review errors in output",
  "priority": "high",
  "category": "error",
  "sound": true
}

Critical Alert (Persistent)

{
  "title": "User Input Required",
  "message": "Please review the following options",
  "priority": "critical",
  "category": "question",
  "sound": true
}

Progress Update

{
  "title": "Processing...",
  "message": "Step 3 of 10 complete",
  "priority": "low",
  "category": "progress",
  "duration": 3000
}

Success Notification

{
  "title": "Deployment Complete",
  "message": "Successfully deployed to production",
  "priority": "normal",
  "category": "success",
  "sound": true
}

Platform Support

The server automatically detects and uses the appropriate notification system:

• macOS 10.8+: Notification Center
• Windows 8+: Toast Notifications
• Windows < 8: Taskbar Balloons
• Linux: notify-send (requires libnotify-bin)

Platform-Specific Behavior

Linux: Priority maps to urgency parameter (low/normal/critical), duration controls timeout precisely

Windows/macOS: Priority and category shown via visual indicators, timeout behavior varies by OS version

Linux Requirements

Install notification support:

# Ubuntu/Debian
sudo apt-get install libnotify-bin

# Fedora
sudo dnf install libnotify

# Arch
sudo pacman -S libnotify