Macos Notify MCP

🚀 macOS Notify MCP

A Model Context Protocol (MCP) server for macOS notifications with tmux integration. This tool enables AI assistants like Claude to send native macOS notifications that can focus specific tmux sessions when clicked.

🚀 Quick Start

macOS Notify MCP is a powerful tool that allows AI assistants to send native macOS notifications and integrate with tmux. Follow the installation and usage steps below to get started.

✨ Features

• 🔔 Send native macOS notifications using the UserNotifications API.
• 🖱️ Create clickable notifications to focus tmux sessions.
• 🎯 Navigate directly to specific tmux sessions, windows, and panes.
• 🔊 Customize notification sounds.
• 🚀 Support multiple concurrent notifications.
• 🤖 Integrate with AI assistants via the MCP server.
• 🖥️ Detect terminal emulators such as VSCode, Cursor, iTerm2, and Terminal.app.

📦 Installation

Prerequisites

• macOS (required for notifications)
• Node.js >= 18.0.0
• tmux (optional, for tmux integration)

Install from npm

npm install -g macos-notify-mcp

Build from source

git clone https://github.com/yuki-yano/macos-notify-mcp.git
cd macos-notify-mcp
npm install
npm run build
npm run build-app  # Build the macOS app bundle (only needed for development)

💻 Usage Examples

As MCP Server

Quick Setup with Claude Code

First, install the package globally:

npm install -g macos-notify-mcp

Use the claude mcp add command:

claude mcp add macos-notify -s user -- macos-notify-mcp

Then restart Claude Code.

Manual Setup for Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "macos-notify": {
      "command": "macos-notify-mcp"
    }
  }
}

Available MCP Tools

• send_notification - Send a macOS notification

  • message (required): Notification message
  • title: Notification title (default: "Claude Code")
  • sound: Notification sound (default: "Glass")
  • session: tmux session name
  • window: tmux window number
  • pane: tmux pane number
  • useCurrent: Use current tmux location

• list_tmux_sessions - List available tmux sessions

• get_current_tmux_info - Get current tmux session information

As CLI Tool

Basic Usage

# Basic notification
macos-notify-cli -m "Build completed"

# With title
macos-notify-cli -t "Development" -m "Tests passed"

# With tmux integration
macos-notify-cli -m "Task finished" -s my-session -w 1 -p 0

# Use current tmux location
macos-notify-cli -m "Check this pane" --current-tmux

# Detect current terminal emulator
macos-notify-cli --detect-terminal

# List tmux sessions
macos-notify-cli --list-sessions

Terminal Detection

The tool automatically detects the terminal emulator you're using and uses this information to focus the correct application when you click on notifications. You can test terminal detection with:

# Test terminal detection
macos-notify-cli --detect-terminal

Supported Terminal Detection

The tool detects terminals using various methods:

1. Cursor: Via CURSOR_TRACE_ID environment variable
2. VSCode: Via VSCODE_IPC_HOOK_CLI or VSCODE_REMOTE environment variables
3. alacritty: Via ALACRITTY_WINDOW_ID or ALACRITTY_SOCKET environment variables
4. iTerm2: Via TERM_PROGRAM=iTerm.app
5. Terminal.app: Via TERM_PROGRAM=Apple_Terminal

Terminal Detection in tmux

When running inside tmux, the tool attempts to detect the terminal emulator used by the active tmux client:

1. Active Client Detection: Identify the most recently active tmux client.
2. TTY Process Analysis: Trace processes using the client's TTY.
3. Environment Preservation: Check preserved environment variables.
4. Process Tree Fallback: Analyze the process tree as a last resort.

For advanced tmux client tracking, see examples/tmux-client-tracking.sh.

🔧 Technical Details

How it Works

1. Notification Delivery: Use a native macOS app bundle (MacOSNotifyMCP.app) to send notifications via the UserNotifications API.
2. Click Handling: When a notification is clicked, the app activates the detected terminal emulator and switches to the specified tmux session.
3. Terminal Support: Automatically detect and activate the correct terminal application.
4. Multiple Instances: Each notification runs as a separate process, allowing multiple concurrent notifications.

Architecture

The project consists of two main components:

1. MCP Server/CLI (TypeScript/Node.js)
   • Implement the Model Context Protocol.
   • Provide a command-line interface.
   • Manage tmux session detection and validation.
2. MacOSNotifyMCP.app (Swift/macOS)
   • A native macOS application for notifications.
   • Handle notification clicks to focus tmux sessions.
   • Run as a background process for each notification.

📚 Documentation

MacOSNotifyMCP.app

The MacOSNotifyMCP.app is bundled with the npm package and is automatically available after installation. No additional setup is required.

Troubleshooting

Notifications not appearing

1. Check System Settings → Notifications → MacOSNotifyMCP.
2. Ensure notifications are allowed.
3. Run macos-notify-mcp -m "test" to verify.

tmux integration not working

1. Ensure tmux is installed and running.
2. Check session names with macos-notify-mcp --list-sessions.
3. Verify that the terminal app is supported (Alacritty, iTerm2, WezTerm, or Terminal).

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development
npm run dev

# Lint and format code
npm run lint
npm run format

# Build macOS app (only if modifying Swift code)
npm run build-app

📄 License

MIT

Author

Yuki Yano