Ntfy Mcp Server

cyanheads/ntfy-mcp-server

Wraps the ntfy push notification service in four tools: publish messages with full parameter coverage (priority, tags, actions, attachments), manage lifecycle events (clear or delete by sequence ID), fetch cached messages with filters, and search the emoji tag reference. Resources expose topic snapshots as `ntfy://{topic}` URIs. Auth is scoped per server, so per-call base URL overrides only forward credentials when they match a registered host. Ships with both STDIO and Streamable HTTP transports. Reach for this when you want Claude to send alerts to your phone or desktop, replay missed notifications, or audit topic activity without writing ntfy API boilerplate.

GitHub stars: 25
tools: 4
auth: Secret needed
transport: STDIO, HTTP
env vars: 20
last updated: Oct 29, 2026

View on GitHub

Tools

4 tools

Public tool metadata for what this MCP can expose to an agent.

ntfy_publish_messageSend or update a push notification on an ntfy topic.

Send or update a push notification on an ntfy topic.

No parameter schema in public metadata yet.

ntfy_manage_messageClear or delete a previously-sent notification by `sequence_id`.

Clear or delete a previously-sent notification by `sequence_id`.

No parameter schema in public metadata yet.

ntfy_fetch_messagesPoll cached messages from one or more topics with optional filters.

Poll cached messages from one or more topics with optional filters.

No parameter schema in public metadata yet.

ntfy_search_emoji_tagsLook up ntfy emoji tag short codes for use in `tags`.

Look up ntfy emoji tag short codes for use in `tags`.

No parameter schema in public metadata yet.

Configuration

NTFY_SERVERS

JSON array of `{ baseUrl, authToken? | authUsername?+authPassword? }` entries — one per ntfy server. First entry is the default base. Auth is scoped to the entry's `baseUrl`; per-call `base_url` overrides that match a registered base forward that server's auth. Takes precedence o

NTFY_BASE_URLdefault: https://ntfy.sh

Single-server shorthand — base URL of the ntfy server (no trailing slash). Used when NTFY_SERVERS is unset.

NTFY_DEFAULT_TOPIC

Topic used when a tool call omits `topic`. Treat the topic name as a secret — anyone who knows it can publish or subscribe.

NTFY_AUTH_TOKEN

Bearer access token (`tk_…`) for the single-server shorthand. Mutually exclusive with NTFY_AUTH_USERNAME / NTFY_AUTH_PASSWORD.

NTFY_AUTH_USERNAME

Basic-auth username for the single-server shorthand — must be set together with NTFY_AUTH_PASSWORD.

NTFY_AUTH_PASSWORD

Basic-auth password for the single-server shorthand — must be set together with NTFY_AUTH_USERNAME.

NTFY_REQUEST_TIMEOUT_MSdefault: 15000

Per-attempt HTTP timeout in milliseconds, covering the response body. Each call is also capped at 50 s across all attempts.

NTFY_MAX_RETRIESdefault: 3

Max retry attempts for transient upstream failures (5xx, network, 429).

NTFY_BLOCK_PRIVATE_HOSTSdefault: false

When true, a per-call `base_url` override must resolve to a public address and its redirects are not followed. Servers registered under NTFY_SERVERS / NTFY_BASE_URL are exempt. Turn it on where callers you do not control can reach the server.

NTFY_ENABLE_EMOJI_TAGSdefault: true

Set to false to disable the ntfy_search_emoji_tags tool: it leaves tools/list, and the server instructions and ntfy_publish_message stop pointing at it.

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

LOGS_DIRdefault: ./logs

Directory for file-based logs (Node only; ignored on Workers).

OTEL_ENABLEDdefault: false

Enable OpenTelemetry instrumentation (spans, metrics, completion logs).

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_SESSION_MODEdefault: stateful

HTTP session model: 'auto', 'stateful', or 'stateless'. This server requires 'stateful' over HTTP — the consent prompt on destructive and outbound calls is a multi-round-trip request that a 2025-era HTTP client can only complete over a live session — so an HTTP start with 'statel

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

MCP_REQUEST_STATE_KEYsecret

Recommended for HTTP. Key (>= 32 bytes, the same on every instance) that seals the requestState carrying the consent-record id of a confirmation prompt, bound to the caller for 900 s; a forged, tampered, or expired state is rejected before the handler runs.