# ntfy-mcp-server

MCP server for dispatching ntfy push notifications to mobile or desktop devices. Useful when coding agents need to ping you about finished tasks or review topic history.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 23
- Author: cyanheads
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cyanheads/ntfy-mcp-server
- Updated: 2026-10-17
- HTML: https://affpapa.org/en/nevibecode/mcp/ntfy-mcp-server

## What it does

This server exposes four tools to publish notifications, clear or delete existing messages, read topic history, and search tag emoji codes. A dedicated resource `ntfy://{topic}` also fetches the twenty most recent messages from the previous hour. It works out of the box with the public ntfy.sh service.

Publishing supports priority levels 1 through 5, action buttons, attachments, and icon links. Message payloads are limited to 4096 bytes. Omitting the body automatically defaults to sending triggered.

A topic gets created on its first publish call. Anyone who discovers the topic name can subscribe or send alerts, so treat topic names as secrets. For safety, the server asks for explicit user confirmation before clearing messages or dispatching external actions.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `NTFY_SERVERS`, `NTFY_BASE_URL`, `NTFY_DEFAULT_TOPIC`, `NTFY_AUTH_TOKEN`, `NTFY_AUTH_USERNAME`, `NTFY_AUTH_PASSWORD`, `NTFY_REQUEST_TIMEOUT_MS`, `NTFY_MAX_RETRIES`, `NTFY_BLOCK_PRIVATE_HOSTS`, `NTFY_ENABLE_EMOJI_TAGS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env NTFY_SERVERS=<NTFY_SERVERS> --env NTFY_BASE_URL=<NTFY_BASE_URL> --env NTFY_DEFAULT_TOPIC=<NTFY_DEFAULT_TOPIC> --env NTFY_AUTH_TOKEN=<NTFY_AUTH_TOKEN> --env NTFY_AUTH_USERNAME=<NTFY_AUTH_USERNAME> --transport stdio ntfy-mcp-server -- npx -y ntfy-mcp-server
```
Replace <…> with your own values. 15 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add ntfy-mcp-server --env NTFY_SERVERS=<NTFY_SERVERS> --env NTFY_BASE_URL=<NTFY_BASE_URL> --env NTFY_DEFAULT_TOPIC=<NTFY_DEFAULT_TOPIC> --env NTFY_AUTH_TOKEN=<NTFY_AUTH_TOKEN> --env NTFY_AUTH_USERNAME=<NTFY_AUTH_USERNAME> -- npx -y ntfy-mcp-server
```
Replace <…> with your own values. 15 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "ntfy-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "ntfy-mcp-server"
            ],
            "env": {
                "NTFY_SERVERS": "<NTFY_SERVERS>",
                "NTFY_BASE_URL": "<NTFY_BASE_URL>",
                "NTFY_DEFAULT_TOPIC": "<NTFY_DEFAULT_TOPIC>",
                "NTFY_AUTH_TOKEN": "<NTFY_AUTH_TOKEN>",
                "NTFY_AUTH_USERNAME": "<NTFY_AUTH_USERNAME>"
            }
        }
    }
}
```
Replace <…> with your own values. 15 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "ntfy-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "ntfy-mcp-server"
            ],
            "env": {
                "NTFY_SERVERS": "<NTFY_SERVERS>",
                "NTFY_BASE_URL": "<NTFY_BASE_URL>",
                "NTFY_DEFAULT_TOPIC": "<NTFY_DEFAULT_TOPIC>",
                "NTFY_AUTH_TOKEN": "<NTFY_AUTH_TOKEN>",
                "NTFY_AUTH_USERNAME": "<NTFY_AUTH_USERNAME>"
            }
        }
    }
}
```
Replace <…> with your own values. 15 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e NTFY_SERVERS=<NTFY_SERVERS> -e NTFY_BASE_URL=<NTFY_BASE_URL> -e NTFY_DEFAULT_TOPIC=<NTFY_DEFAULT_TOPIC> -e NTFY_AUTH_TOKEN=<NTFY_AUTH_TOKEN> -e NTFY_AUTH_USERNAME=<NTFY_AUTH_USERNAME> ntfy-mcp-server npx -y ntfy-mcp-server
```
Replace <…> with your own values. 15 more environment variables are in the server README

## When to use it
- send a phone notification when a background build finishes
- inspect recent messages published to an ntfy topic
- dismiss or delete a stale push notification by its sequence ID
- look up shortcode tags for notification emojis

## Example prompts
- Send a priority 5 push notification to the release-alerts topic saying deployment succeeded
- Fetch the latest messages from the monitoring topic over the past 30 minutes
- Clear the notification with sequence_id 849 from topic dev-updates

## Similar
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [AIHawk](https://affpapa.org/en/nevibecode/mcp/aihawk.md) — MCP server · ★ 32221
- [Skyvern](https://affpapa.org/en/nevibecode/mcp/skyvern.md) — MCP server · ★ 23263
- [SeleniumBase MCP](https://affpapa.org/en/nevibecode/mcp/seleniumbase-mcp.md) — MCP server · ★ 13169
- [Inbox Zero](https://affpapa.org/en/nevibecode/mcp/inbox-zero.md) — MCP server · ★ 12791

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md