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

2. 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