Overview

Push notifications over the ntfy pub/sub HTTP API. Publish, update, and manage notifications, poll cached topic history, and look up emoji short codes for tags from any MCP client. Runs as a stdio process or a local Streamable HTTP server.

Tools

| Tool | Description | |:---|:---| | ntfy_publish_message | Send or update a push notification on an ntfy topic. | | ntfy_manage_message | Clear or delete a previously-sent notification by sequence_id. | | ntfy_fetch_messages | Poll cached messages from one or more topics with optional filters. | | ntfy_search_emoji_tags | Look up ntfy emoji tag short codes for use in tags. |

Resources

| Resource | Description | |:---|:---| | ntfy://{topic} | Snapshot of a topic — latest 20 messages from the past hour, plus the topic's browser URL. |

ntfy_fetch_messages covers the same topic data with custom windows and filters when the resource's fixed defaults aren't enough.

Capability reference

ntfy_publish_message tool

• Topics are created on first publish — treat the topic name as a secret; anyone who knows it can publish or subscribe
• Full publish-parameter coverage — title, priority (1–5), tags, click, attach, icon, filename, markdown, delay, email, call, cache, firebase; message body capped at 4096 bytes (non-ASCII characters cost more), empty body defaults server-side to triggered
• Up to three discriminated action buttons (view, broadcast, http, copy) per message
• Update or replace a previously-sent message by passing the original sequence_id
• Per-call base_url override forwards credentials only when it matches a registered server (NTFY_BASE_URL or an NTFY_SERVERS entry); otherwise the request goes out unauthenticated
• Publishes carrying email, call, or a broadcast/http action button ask the user to confirm the specific target first — the call returns a confirmation request, and sends only once reissued with the answer

ntfy_manage_message tool

• operation: clear marks the notification read & dismisses it (subscribers see message_clear); delete removes it from the drawer (subscribers see message_delete)
• Append-only — the original message stays in cache; re-issuing the same operation is safe, though a fresh event fires each call
• Every call asks the user to confirm the topic, sequence_id, and operation before the event fires — the first call returns that confirmation request, and declining fails with consent_declined
• ntfy.sh accepts an unknown sequence_id without error; stricter ntfy deployments return a not_found failure instead

ntfy_fetch_messages tool

• Returns a snapshot, not a live stream — use it to confirm delivery, replay missed alerts, or audit topic activity
• Comma-separated multi-topic queries (e.g. alerts,backups,phil_alerts)
• Filter by since (duration / timestamp / message ID / all / latest), priority, tags, id, title, message, scheduled-only
• Default window 10m, default limit 20 messages per response, hard cap 100 — over-limit windows keep the newest limit messages, listed oldest-first
• Long bodies truncated to ~500 chars with messageTruncated reporting the dropped count; refetch with a message id to read that one in full

ntfy_search_emoji_tags tool

• Substring match against tag names, case-insensitive; omit query to list the reference from the start in its documented order
• limit default 25, max 200; offset pages past the cap using the returned totalCount
• Returned tag strings plug directly into ntfy_publish_message's tags field

ntfy://{topic} resource

• Fixed snapshot — latest 20 messages from the past 1 hour, plus the topic's browser URL; same normalized message shape as ntfy_fetch_messages (ISO 8601 timestamps, ~500-char body truncation)
• For custom windows, filters, or replay, use ntfy_fetch_messages instead

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

ntfy-specific:

• Wraps ntfy's HTTP API with a retry-aware client (withRetry + per-request timeout)
• Per-server scoped auth — credentials bind to each registered base URL (NTFY_BASE_URL or an NTFY_SERVERS entry); mutually-exclusive bearer-token / basic-auth modes validated at config load; a per-call base_url override forwards auth only when it matches a registered server
• User confirmation before side effects that leave the notification drawer — a clear/delete, or a publish carrying email, call, or a broadcast/http action button — enforced on both stdio and Streamable HTTP
• Optional SSRF guard on base_url overrides (NTFY_BLOCK_PRIVATE_HOSTS) — blocks loopback, RFC 1918, RFC 6598 mesh, link-local, and IPv6 equivalents, then refuses redirects; registered servers are exempt
• Bundled emoji-tag reference, regenerated from upstream docs/ntfy/emojis.md via scripts/build-emoji-tags.ts

Agent-friendly output:

• Provenance — ntfy_publish_message and ntfy_manage_message echo back the resolved topic, ID, and timestamp; ntfy_fetch_messages also echoes the resolved since and applied filters
• Discriminated outputs — typed reason codes (consent_declined, forbidden_topic, rate_limited, not_found, payload_too_large, and more) on every tool's error contract let callers branch on failure mode instead of parsing error text
• Truncation and paging guidance — ntfy_fetch_messages and ntfy_search_emoji_tags report a truncated flag plus a notice naming the exact next step (widen since, raise limit, advance offset) instead of silently dropping results

Getting started

Add the following to your MCP client configuration file. Public ntfy.sh works out of the box without an account; for protected topics, generate an access token at https://ntfy.sh/account.

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ntfy-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "NTFY_DEFAULT_TOPIC": "your-topic-name"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "ntfy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "NTFY_DEFAULT_TOPIC=your-topic-name",
        "ghcr.io/cyanheads/ntfy-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NTFY_DEFAULT_TOPIC=your-topic bun run start:http
# Server listens at http://127.0.0.1:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• A topic name on an ntfy server. Public ntfy.sh requires no account; self-hosted instances and protected topics may need a bearer token or basic-auth credentials.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/ntfy-mcp-server.git

2. Navigate into the directory:

cd ntfy-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set NTFY_DEFAULT_TOPIC (and auth, if needed)

Configuration

| Variable | Description | Default | |:---------|:------------|:--------| | 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. Use this when you need more than one authenticated server in a single process; it takes precedence over the single-server vars below. | — | | NTFY_BASE_URL | Single-server shorthand — base URL of the ntfy server (no trailing slash). Used when NTFY_SERVERS is unset. | https://ntfy.sh | | NTFY_DEFAULT_TOPIC | Topic used when a tool call omits topic. | — | | 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 — required together with NTFY_AUTH_PASSWORD. | — | | NTFY_AUTH_PASSWORD | Basic-auth password for the single-server shorthand — required together with NTFY_AUTH_USERNAME. | — | | NTFY_REQUEST_TIMEOUT_MS | Per-request HTTP timeout in milliseconds. | 15000 | | NTFY_MAX_RETRIES | Max retry attempts for transient upstream failures (5xx, network, 429). | 3 | | NTFY_BLOCK_PRIVATE_HOSTS | 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, so a deliberate LAN target still works. Turn it on where callers you don't control can reach the server. | false | | MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio | | MCP_SESSION_MODE | 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 stateless is refused. auto resolves to stateful; stdio ignores the setting. | stateful | | MCP_HTTP_HOST | HTTP host. | 127.0.0.1 | | MCP_HTTP_PORT | HTTP port. | 3010 | | MCP_HTTP_ENDPOINT_PATH | HTTP endpoint path. | /mcp | | MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none | | MCP_LOG_LEVEL | Log level (RFC 5424). | info | | LOGS_DIR | Directory for file-based logs (Node only; ignored on Workers). | ./logs | | OTEL_ENABLED | Enable OpenTelemetry instrumentation (spans, metrics, completion logs). | false |

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck     # Lint, format, typecheck, security, changelog sync
  bun run test         # Vitest test suite
  bun run lint:mcp     # Validate MCP definitions against spec

Docker

docker build -t ntfy-mcp-server .
docker run --rm -e NTFY_DEFAULT_TOPIC=your-topic -p 3010:3010 ntfy-mcp-server

The Dockerfile defaults to HTTP transport, stateful session mode, and logs to /var/log/ntfy-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

| Directory | Purpose | |:----------|:--------| | src/index.ts | createApp() entry point — registers tools and resources, initializes services. | | src/config | Server-specific environment variable parsing (NTFY_*) with Zod. | | src/mcp-server/tools | Tool definitions (*.tool.ts). | | src/mcp-server/resources | Resource definitions (*.resource.ts). | | src/services/ntfy | ntfy HTTP client, types, and error classifier. | | src/services/emoji-tags | Bundled emoji short-code reference and lookup service. | | docs/ntfy | Mirrored upstream ntfy API docs (pinned commit in SOURCES.md). | | tests/ | Unit and integration tests mirroring src/. |

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
• Per-tool errors[] contracts stay inline — repetition is intended for locality

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.