desktop-notification-mcp

GhostTypes/desktop-notification-mcp

3.1

If you are the rightful owner of desktop-notification-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 dayong@mcphub.com.

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

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

ParameterTypeDefaultDescription
titlestringrequiredNotification title
messagestringrequiredNotification message body
soundbooleanfalseEnable notification sound
prioritystring"normal"Priority level: "low", "normal", "high", "critical"
categorystring"task"Category: "task", "error", "success", "progress", "question", "reminder"
durationnumberautoDisplay 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