macOS Utilities

Provides macOS utility tools for AI assistants, including sending native notifications with project context.

GitHub

mcp-macos-utils

A Model Context Protocol (MCP) server that provides macOS utility tools for AI assistants.

Features

  • Native macOS Notifications: Send system notifications with different types (success, error, info, warning)
  • Auto Project Detection: Automatically detects and includes the current project name in notifications
  • Notification Logging: All notifications are logged to ~/.mcp-notifications.log for audit trail
  • TypeScript Support: Fully typed for better development experience

Installation

  1. Clone this repository:
git clone <repository-url>
cd mcp-macos-utils
  1. Run the install script:
./install.sh

This will:

  • Install npm dependencies
  • Build the TypeScript code
  • Create an example configuration file

Configuration

Add the following to your MCP client's configuration file:

{
  "mcpServers": {
    "macos-utils": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-macos-utils/dist/index.js"],
      "env": {}
    }
  }
}

Replace /absolute/path/to/mcp-macos-utils with the actual path to this directory.

Usage

Once configured, the following tool will be available to AI assistants:

notify

Send a macOS notification with project context.

Parameters:

  • title (required): The notification title
  • message (required): The notification message
  • type (optional): Type of notification - success, error, info, or warning (default: info)
  • sound (optional): Whether to play a sound (default: true)
  • subtitle (optional): Custom subtitle (defaults to current project name)

Example:

await notify({
  title: "Build Complete",
  message: "Your project has been built successfully",
  type: "success"
});

Notification Types

  • Success (✅): For successful operations
  • Error (❌): For errors or failures
  • Warning (⚠️): For warnings or cautions
  • Info (ℹ️): For general information

Logging

All notifications are logged to ~/.mcp-notifications.log in JSON format, including:

  • Timestamp
  • Project name
  • Notification type
  • Title and message
  • Any errors that occurred

Development

Building

npm run build

Development Mode

npm run dev

Clean Build

npm run clean
npm run build

Requirements

  • macOS (uses native osascript for notifications)
  • Node.js 20+
  • TypeScript 5.5+

License

MIT

Related Servers