# MCP Notifications Server

A Model Context Protocol (MCP) server that enables Claude and other MCP clients to display native macOS notifications.

## Features

- **show_notification** tool for displaying notifications on macOS
- Support for custom titles and content
- Optional icon and sound parameters
- Uses macOS Notification Center

## Prerequisites

- Node.js (v18 or later)
- macOS (for notification support)
- npm or yarn

## Installation

1. Clone or download this repository
2. Install dependencies:

```bash
npm install
```

3. Build the TypeScript code:

```bash
npm run build
```

## Usage with Claude Desktop

Add this server to your Claude Desktop configuration file:

**Location:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "notifications": {
      "command": "node",
      "args": ["/Users/konstantinzagulin/IdeaProjects/mcp-notifications/build/index.js"]
    }
  }
}
```

Replace the path with the actual path to your installation.

## Tool: show_notification

Display a notification on macOS.

### Parameters

- **title** (required): The title of the notification
- **content** (required): The main message content
- **icon** (optional): Path to an icon file (e.g., `/path/to/icon.png`)
- **sound** (optional): System sound name to play (e.g., `Ping`, `Basso`, `Hero`, `Funk`, `Glass`, `Pop`, `Submarine`, `Blow`, `Bottle`, `Frog`, `Morse`, `Purr`, `Sosumi`, `Tink`)

### Example Usage

In Claude Desktop, you can ask Claude to show notifications:

```
Show me a notification with title "Task Complete" and message "Your build finished successfully"
```

```
Display a notification titled "Reminder" with the message "Meeting in 5 minutes" and use the Ping sound
```

## Development

### Project Structure

```
mcp-notifications/
├── src/
│   └── index.ts        # Main MCP server implementation
├── build/              # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
```

### Building

```bash
npm run build
```

### Testing Locally

You can test the server by running it directly:

```bash
node build/index.js
```

The server communicates via stdio, so you'll need an MCP client to interact with it properly.

## How It Works

This MCP server uses:
- **@modelcontextprotocol/sdk**: Official MCP SDK for TypeScript
- **node-notifier**: Cross-platform notification library that uses macOS Notification Center on macOS

The server exposes a single tool (`show_notification`) that accepts notification parameters and displays them using the native macOS notification system.

## License

MIT