ntfy-mcp-server — Claude Code MCP server: what it does, how to install
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.
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-serverWhat ntfy-mcp-server 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.
What it helps with
- 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 for the agent
- 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
How to install ntfy-mcp-server
Platform CLI
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-serverReplace <…> with your own values. 15 more environment variables are in the server README
Platform CLI
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-serverReplace <…> with your own values. 15 more environment variables are in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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-serverReplace <…> with your own values. 15 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ntfy-mcp-server
How to install ntfy-mcp-server in Claude Code?
Run claude mcp add ntfy-mcp-server -- npx -y ntfy-mcp-server in your terminal. If you need private server credentials, pass environment variables with --env.
What does ntfy-mcp-server do?
It connects AI coding assistants to ntfy push notifications. The agent can send mobile alerts, inspect topic logs, and manage sent messages.
Does the server require confirmation before modifying messages?
Yes. Every message clear or delete operation prompts the user for consent before executing.
