Notifications

Provides native macOS notifications to Claude via MCP, enabling alerts and interactions on macOS.

typescript

0

GitHub Stars

typescript

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ohqay-notifications": {
      "command": "node",
      "args": [
        "/absolute/path/to/notifications/build/index.js"
      ]
    }
  }
}

You can enable AI assistants to send native macOS notifications through this MCP server, giving you timely alerts, reminders, and quick replies directly from Claude or similar assistants. It bridges your AI prompts with the macOS Notification Center so you can stay informed without leaving your workflow.

How to use

Use this MCP server by connecting it to your MCP client. After installation, your AI assistant can trigger macOS notifications with customizable titles, messages, sounds, and actions. You can ask for alerts when tasks start or finish, when attention is needed, or for periodic reminders. You can also enable interactive notifications that you can reply to or respond to with action buttons.

How to install

Prerequisites: you need a working Node.js environment and the Bun runtime for building and configuring the Claude integration.

# Clone the project repository
git clone https://github.com/ohqay/notifications.git
cd notifications

# Install dependencies using Bun
bun install

# Build and configure for Claude Desktop (automatic setup)
bun run setup-claude

Manual configuration

If you configure manually, add the MCP server configuration to your Claude Desktop settings. The following snippet demonstrates the exact JSON you would place under mcpServers.

{
  "mcpServers": {
    "notifications": {
      "command": "node",
      "args": ["/absolute/path/to/notifications/build/index.js"]
    }
  }
}

Troubleshooting

If notifications don’t appear, ensure macOS permissions and system settings allow terminal-based notifications. Common issues include disabled notifications, Focus mode blocking alerts, Do Not Disturb being active, or first-time permission prompts. These problems are typically resolved by enabling notifications for Terminal and allowing the app to display alerts.

Notes and limitations

Notifications show a Terminal icon in the macOS Notification Center when sent from command-line tools.
A maximum of 2 action buttons can be attached to a single notification.
Some features require macOS 10.9 or higher.

Development

You can build, watch, and run the server locally using the included Bun scripts.

bun run build
bun run watch
bun run dev

Project structure

The project includes a TypeScript source, a compiled build output, and setup scripts that integrate with Claude Desktop.

Security and handling

The server exposes a notification API that accepts titles, messages, sounds, and optional user interactions. Use with caution to avoid alert fatigue and ensure sensitive information isn’t exposed in notifications.

Examples of usage

Basic prompts to trigger notifications include requests like alerting when a task completes or sending a reminder at a specified time. Advanced prompts can specify sounds, interactive replies, and action buttons.

Available tools

send_notification

An endpoint exposed by the MCP server to AI assistants that composes and dispatches native macOS notifications with configurable title, message, sounds, duration, reply capability, actions, icons, and content imagery.