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