send_notification

Send native macOS notifications with tmux integration to focus specific tmux sessions when clicked, enabling AI assistants to deliver system alerts.

Instructions

Send a macOS notification with optional tmux integration

Input Schema

TableJSON Schema

Name	Required	Description
`message`	Yes	The notification message
`title`	No	The notification title (default: "Claude Code")
`sound`	No	The notification sound (default: "Glass")
`session`	No	tmux session name
`window`	No	tmux window number
`pane`	No	tmux pane number
`useCurrent`	No	Use current tmux location

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
}

macOS Notify MCP