macOS Notify MCP

Instructions

Implementation Reference

• src/index.ts:113-174 (handler)

  MCP tool handler for send_notification: validates inputs, handles tmux current/useCurrent logic, session validation, and calls notifier.sendNotification
  case 'send_notification': { // Safely extract properties from args const notificationArgs = args as Record<string, unknown> // Validate message is provided if (!notificationArgs.message) { throw new Error('Message is required') } const options: NotificationOptions = { message: String(notificationArgs.message), title: notificationArgs.title ? String(notificationArgs.title) : undefined, sound: notificationArgs.sound ? String(notificationArgs.sound) : undefined, } if (notificationArgs.useCurrent) { const current = await notifier.getCurrentTmuxInfo() if (current) { options.session = current.session options.window = current.window options.pane = current.pane } } else { if (notificationArgs.session) options.session = String(notificationArgs.session) if (notificationArgs.window) options.window = String(notificationArgs.window) if (notificationArgs.pane) options.pane = String(notificationArgs.pane) } // Validate session if specified if (options.session) { const exists = await notifier.sessionExists(options.session) if (!exists) { const sessions = await notifier.listSessions() return { content: [ { type: 'text', text: `Error: Session '${options.session}' does not exist. Available sessions: ${sessions.join(', ')}`, }, ], } } } await notifier.sendNotification(options) return { content: [ { type: 'text', text: `Notification sent: "${options.message}"${options.session ? ` (tmux: ${options.session})` : ''}`, }, ], } }
• src/index.ts:48-81 (schema)

  Input schema for the send_notification tool defining parameters and validation rules
  inputSchema: { type: 'object', properties: { message: { type: 'string', description: 'The notification message', }, title: { type: 'string', description: 'The notification title (default: "Claude Code")', }, sound: { type: 'string', description: 'The notification sound (default: "Glass")', }, session: { type: 'string', description: 'tmux session name', }, window: { type: 'string', description: 'tmux window number', }, pane: { type: 'string', description: 'tmux pane number', }, useCurrent: { type: 'boolean', description: 'Use current tmux location', }, }, required: ['message'], },
• src/index.ts:45-82 (registration)

  Registration of the send_notification tool in the MCP tools list response
  { name: 'send_notification', description: 'Send a macOS notification with optional tmux integration', inputSchema: { type: 'object', properties: { message: { type: 'string', description: 'The notification message', }, title: { type: 'string', description: 'The notification title (default: "Claude Code")', }, sound: { type: 'string', description: 'The notification sound (default: "Glass")', }, session: { type: 'string', description: 'tmux session name', }, window: { type: 'string', description: 'tmux window number', }, pane: { type: 'string', description: 'tmux pane number', }, useCurrent: { type: 'boolean', description: 'Use current tmux location', }, }, required: ['message'], }, },
• src/notifier.ts:452-497 (helper)

  Helper function implementing the actual notification sending logic via MacOSNotifyMCP.app, including terminal detection and tmux targeting
  async sendNotification(options: NotificationOptions): Promise<void> { const { title = this.defaultTitle, message, sound = 'Glass', session, window, pane, } = options // Check if app path is valid if (!this.appPath) { throw new Error('MacOSNotifyMCP.app not found') } // Always detect terminal emulator to pass to notification app const terminal = await this.detectTerminalEmulator() // Use MacOSNotifyMCP.app for notifications const args = [ '-n', this.appPath, '--args', '-t', title, '-m', message, '--sound', sound, '--terminal', terminal, ] if (session) { args.push('-s', session) if (window !== undefined && window !== '') { args.push('-w', window) } if (pane !== undefined && pane !== '') { args.push('-p', pane) } } await this.runCommand('/usr/bin/open', args) } }
• src/index.ts:12-19 (schema)

  Type definition for NotificationOptions used in the handler
  interface NotificationOptions { message: string title?: string sound?: string session?: string window?: string pane?: string }