# Simple Ntfy MCP Server

[![npm version](https://badge.fury.io/js/simple-ntfy-mcp.svg)](https://www.npmjs.com/package/simple-ntfy-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A simple MCP (Model Context Protocol) server for sending push notifications via [ntfy.sh](https://ntfy.sh). Works seamlessly with Claude Desktop and other MCP-compatible clients.

## Features

- **Zero configuration** - Works out of the box with npx
- **Push notifications** - Send notifications to any device via ntfy
- **Lightweight** - Minimal dependencies
- **Customizable** - Support for titles, priorities, tags, click actions, and action buttons

## Installation & Usage

### With npx (Recommended)

No installation needed! Just add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "ntfy": {
      "command": "npx",
      "args": ["-y", "simple-ntfy-mcp"],
      "env": {
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}
```

### Global Installation

```bash
npm install -g simple-ntfy-mcp
```

Then use in your Claude Desktop config:

```json
{
  "mcpServers": {
    "ntfy": {
      "command": "simple-ntfy-mcp",
      "env": {
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `NTFY_DEFAULT_TOPIC` | Default topic to send notifications to | *(required)* |
| `NTFY_BASE_URL` | Base URL of ntfy server | `https://ntfy.sh` |

## Tool: `send_ntfy`

Send a push notification to your configured ntfy topic.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `message` | string | ✅ | The notification message |
| `topic` | string | ❌ | Topic to send to (uses default if not specified) |
| `title` | string | ❌ | Notification title |
| `priority` | number | ❌ | Priority level 1-5 (default: 3) |
| `tags` | string[] | ❌ | Array of [tags/emojis](https://docs.ntfy.sh/emojis/) |
| `click` | string | ❌ | URL to open when notification is clicked |
| `actions` | object[] | ❌ | [Action buttons](https://docs.ntfy.sh/publish/#action-buttons) |

### Example Usage

Once configured, you can ask Claude to send you notifications:

> "Send me a notification when you're done with this task"

Or be more specific:

> "Send a high priority notification with the title 'Build Complete' and message 'Your project has finished building'"

### Example Tool Call

```json
{
  "message": "Your task is complete!",
  "title": "Task Completed",
  "priority": 4,
  "tags": ["white_check_mark", "rocket"],
  "click": "https://example.com"
}
```

## What is ntfy?

[ntfy](https://ntfy.sh) is a simple HTTP-based pub-sub notification service. It allows you to send push notifications to your phone or desktop from any script or application. It's free, open source, and you can even self-host it.

To receive notifications:
1. Install the ntfy app on your [Android](https://play.google.com/store/apps/details?id=io.heckel.ntfy) or [iOS](https://apps.apple.com/app/ntfy/id1625396347) device
2. Subscribe to your chosen topic
3. Configure this MCP server with the same topic name

## License

MIT