Prepare the server locally
Run this once before adding it to Claude Code.
git clone <repository-url>
cd mcp-macos-utils
./install.shRegister it in Claude Code
claude mcp add macos-utils -- node /absolute/path/to/mcp-macos-utils/dist/index.jsReplace any placeholder paths in the command with the real path on your machine.
Make your agent remember this setup
macos-utils's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Native macOS system notifications
- Automatic project name detection for notification context
- Audit trail logging of all notifications to ~/.mcp-notifications.log
- Support for different notification types: success, error, info, and warning
Tools 1
notifySend a macOS notification with project context.Try it
Original README from msageryd/mcp-macos-utils
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.logfor audit trail - TypeScript Support: Fully typed for better development experience
Installation
- Clone this repository:
git clone <repository-url>
cd mcp-macos-utils
- 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 titlemessage(required): The notification messagetype(optional): Type of notification -success,error,info, orwarning(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
osascriptfor notifications) - Node.js 20+
- TypeScript 5.5+
License
MIT