# mcp-ntfy

MCP server for [ntfy](https://ntfy.sh) push notifications. Send and poll notifications from any MCP-compatible client.

## Installation

```bash
npx mcp-ntfy
```

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ntfy": {
      "command": "npx",
      "args": ["-y", "mcp-ntfy"],
      "env": {
        "NTFY_URL": "https://ntfy.sh",
        "NTFY_TOKEN": "tk_...",
        "NTFY_TOPIC": "my-notifications"
      }
    }
  }
}
```

### Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "ntfy": {
      "command": "npx",
      "args": ["-y", "mcp-ntfy"],
      "env": {
        "NTFY_URL": "https://ntfy.sh",
        "NTFY_TOKEN": "tk_...",
        "NTFY_TOPIC": "my-notifications"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `NTFY_URL` | No | `https://ntfy.sh` | ntfy server base URL |
| `NTFY_TOKEN` | No | — | Bearer token for authentication |
| `NTFY_TOPIC` | No | — | Default topic (used when tool calls omit topic) |

## Tools

### `publish`

Send a push notification to an ntfy topic.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `topic` | string | No* | Topic name (*required if `NTFY_TOPIC` not set) |
| `message` | string | Yes | Notification body |
| `title` | string | No | Notification title |
| `priority` | number | No | 1=min, 2=low, 3=default, 4=high, 5=urgent |
| `tags` | string[] | No | Emoji shortcodes, e.g. `["warning", "skull"]` |
| `click` | string | No | URL to open on tap |
| `attach` | string | No | File URL to attach |
| `filename` | string | No | Attachment filename |
| `icon` | string | No | Notification icon URL |
| `delay` | string | No | Delay: `"30m"`, `"2h"`, `"tomorrow 9am"` |
| `markdown` | boolean | No | Enable Markdown formatting |
| `actions` | Action[] | No | Up to 3 action buttons |

### `poll`

Poll for cached messages from an ntfy topic.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `topic` | string | No* | Topic to poll (*required if `NTFY_TOPIC` not set) |
| `since` | string | No | Duration (`"10m"`), timestamp, ID, `"all"`, or `"latest"` |
| `scheduled` | boolean | No | Include scheduled messages |
| `id` | string | No | Filter by message ID |
| `message` | string | No | Filter by message text |
| `title` | string | No | Filter by title |
| `priority` | string | No | Filter by priority (comma-separated) |
| `tags` | string | No | Filter by tags (comma-separated, AND logic) |

### `server_health`

Check ntfy server health status and message statistics. No parameters.

## License

MIT