MacOS Notify

Provides native macOS notifications with tmux-focused navigation via an MCP server.

typescript

13

GitHub Stars

typescript

Language

6 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": {
    "yuki-yano-macos-notify-mcp": {
      "command": "macos-notify-mcp",
      "args": []
    }
  }
}

You can send native macOS notifications from an MCP client and have them focus specific tmux sessions when clicked. This server enables smooth, clickable alerts that navigate you to the right tmux context, with optional sounds and multi-notification support.

How to use

Install and run the MCP server on your macOS machine, then connect from your MCP client to send notifications. When a notification is clicked, it will activate the appropriate terminal emulator (VSCode, Cursor, iTerm2, WezTerm, or Terminal.app) and switch to the specified tmux session, window, and pane.

How to install

Prerequisites: macOS, Node.js >= 18.0.0, and tmux (optional for tmux integration). Ensure you have these before proceeding.

Install the MCP server from npm:

npm install -g macos-notify-mcp

Usage and configuration

Run the MCP server locally to expose the notification functionality. The server can be invoked directly as a standalone MCP server for integration with your clients.

Example quick setup with Claude Code for integrating Claude’s MCP client is shown by registering the server endpoint with your MCP client setup. Use the server name macos-notify as the MCP server alias and ensure it is added to your client’s MCP server list.

Troubleshooting

Notifications not appearing or not focusing tmux sessions can have several causes. Verify macOS notification permissions for MacOSNotifyMCP, confirm tmux is running, and ensure your target tmux session/window/pane names are correct.

Test the server locally by sending a simple notification and confirming the click behavior focuses the designated tmux location.

Development

If you need to build from source for development, follow these steps.

# 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

Available tools

send_notification

Send a macOS notification with optional title, sound, and tmux targeting details like session, window, and pane.

list_tmux_sessions

List available tmux sessions to pick a target for a notification.

get_current_tmux_info

Retrieve current tmux session information to help configure notifications that reflect the active context.