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

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

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"
});

Requirements

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

License

MIT