mcp-ntfy

MCP server for ntfy push notifications. Send and poll notifications from any MCP-compatible client.

Installation

npx mcp-ntfy

Configuration

Claude Desktop

Add to your claude_desktop_config.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:

{
  "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