macOS-Notification

This MCP server enables AI assistants to trigger macOS notifications, play system sounds, and convert text to speech. It exposes tools for sound notifications, banner (visual) notifications, speech synthesis, voice management, and testing utilities. You can control these capabilities through the provided Python API calls (e.g., sound_notification, banner_notification, speak_notification, list_available_voices, test_notification_system) or via Claude Desktop integration if you’re using Claude’s workflow. The server processes requests sequentially, with built-in queuing and a small delay between notifications to avoid overlap, and relies on native macOS commands (afplay, osascript, say) for implementation.

To run, use the recommended uvx-based approach: launch the MCP server with the uvx runtime, which avoids permanent installation. Example command: uvx macos-notification-mcp. The server is designed to be easily integrated into automation, chat assistants, or Claude Desktop configurations so you can trigger notifications directly from your AI workflows.

Prerequisites:

• macOS (since it uses native macOS tooling)
• Python 3.x (for the Python API and optional development)
• Optional: uv (via the uvx runtime) for zero-install usage

Installation steps (uvx / runtime method):

1. Install uv if you don't have it (recommended): curl -LsSf https://astral.sh/uv/install.sh | sh
2. Run the MCP server directly without permanent installation: uvx macos-notification-mcp

Alternative installation (pip / from source):

1. Install the package via pip: pip install macos-notification-mcp
2. Install from source (if you prefer): git clone https://github.com/devizor/macos-notification-mcp cd macos-notification-mcp pip install .
3. Run the server (if installed via pip): python -m macos_notification_mcp # adjust if the exact entry point differs in your install

Note: The README describes using uvx for quick usage and the pip method for a more permanent install. Choose the method that best fits your workflow.

Tips and common considerations:

• Permissions: Ensure macOS Notifications are allowed for this app in System Settings → Notifications.
• If using the direct command (not uvx), you may need to supply full paths to system tools (afplay, osascript, say).
• Rate limiting: The server processes one notification at a time with a minimum interval of 0.5 seconds to avoid overlaps.
• Environment: When running in certain automation environments, ensure the user session has access to GUI elements for notifications.
• Troubleshooting: If notifications don't appear, check Console for any errors related to osascript or say; verify that the correct system voices are installed for text-to-speech.
• Testing: Use test_notification_system() to validate all notification methods during development.