\n\n[](https://github.com/cyanheads/ntfy-mcp-server/releases/latest/download/ntfy-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=ntfy-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm50ZnktbWNwLXNlcnZlciJdfQ==) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22ntfy-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22ntfy-mcp-server%22%5D%7D)\n\n
\n\n---\n\n## Tools\n\nFour tools covering the ntfy publish/subscribe surface — message lifecycle (publish, manage, fetch) plus an emoji-tag lookup that feeds the publish tool's `tags` field:\n\n| Tool Name | Description |\n|:----------|:------------|\n| `ntfy_publish_message` | Send or update a push notification on an ntfy topic. |\n| `ntfy_manage_message` | Clear or delete a previously-sent notification by `sequence_id`. |\n| `ntfy_fetch_messages` | Poll cached messages from one or more topics with optional filters. |\n| `ntfy_search_emoji_tags` | Look up ntfy emoji tag short codes for use in `tags`. |\n\n---\n\n### `ntfy_publish_message`\n\nSend or update a push notification on an ntfy topic. Topics are created on first publish — treat the topic name as a secret because anyone who knows it can publish or subscribe.\n\n- Full publish-parameter coverage — `title`, `priority` (1–5), `tags`, `click`, `attach`, `icon`, `filename`, `markdown`, `delay`, `email`, `call`, `cache`, `firebase`\n- Up to three discriminated action buttons (`view`, `broadcast`, `http`, `copy`) per message\n- Update or replace previously-sent messages by passing the original `sequence_id`\n- Per-call `base_url` override that forwards credentials only when the override matches a registered server (`NTFY_BASE_URL` or an `NTFY_SERVERS` entry); otherwise the request goes out unauthenticated, so credentials never leak to alternate hosts\n- Publishes carrying `email`, `call`, or a `broadcast` / `http` action button ask the user to confirm the specific recipient or target first — the call comes back requesting that confirmation, and the message goes out only when it is reissued with the answer attached\n\n---\n\n### `ntfy_manage_message`\n\nClear (mark read & dismiss) or delete a previously-sent ntfy notification by `sequence_id`. Append-only — the original message stays in cache, and a `message_clear` / `message_delete` event is emitted to subscribers. Idempotent.\n\n- Every call asks the user to confirm the topic, `sequence_id`, and operation before the event fires — the first call comes back requesting that confirmation, and declining fails the call with `consent_declined`\n\n---\n\n### `ntfy_fetch_messages`\n\nPoll cached messages from one or more topics with optional filters. Returns a snapshot, not a live stream — use it to confirm delivery, replay missed alerts, or audit topic activity.\n\n- Comma-separated multi-topic queries (e.g. `alerts,backups,phil_alerts`)\n- Filter by `since` (duration / timestamp / message ID / `all` / `latest`), `priority`, `tags`, `id`, `title`, `message`, scheduled-only\n- Default window `10m`, default limit 20 messages per response, hard cap 100 — over-limit windows keep the newest `limit` messages, listed oldest-first\n- Long bodies truncated to ~500 chars with `messageTruncated` reporting the dropped count; refetch with a message `id` to read that one in full\n\n---\n\n### `ntfy_search_emoji_tags`\n\nSubstring search over the bundled ntfy emoji-tag reference. Returns the `tag` strings ready to plug into `ntfy_publish_message`'s `tags` field. Without a query, returns the first slice of the full reference; `offset` pages through matches beyond the `limit` cap.\n\n## Resources and prompts\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `ntfy://{topic}` | Snapshot of a topic — 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 and ~500-char body truncation. |\n\n`ntfy_fetch_messages` covers the same topic data with custom windows and filters when the resource's fixed defaults aren't enough.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation\n- Typed error contracts via `ctx.fail(reason, …)` plus framework error factories (`forbidden`, `notFound`, `validationError`, …)\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nntfy-specific:\n\n- Wraps ntfy's HTTP API with retry-aware client (`withRetry` + per-request timeout)\n- Per-server scoped auth — credentials are bound to each registered base URL (`NTFY_BASE_URL` or per-entry under `NTFY_SERVERS`); per-call `base_url` overrides forward auth only when the override matches a registered server, and go out unauthenticated otherwise\n- 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. The tool returns a confirmation request naming the exact target, and acts only on the reissued call that carries an approval. Enforced on both STDIO and Streamable HTTP; a client that cannot present the prompt gets an error instead of an unasked side effect\n- Optional SSRF guard on `base_url` overrides (`NTFY_BLOCK_PRIVATE_HOSTS`) — resolves the host and blocks every reserved destination it answers on (loopback, RFC 1918, RFC 6598 mesh space, link-local, and the IPv6 equivalents), then refuses redirects, with registered servers exempt\n- Bundled emoji-tag reference, regenerated from upstream `docs/ntfy/emojis.md` via `scripts/build-emoji-tags.ts`\n- Mutually-exclusive auth modes (bearer token *or* basic auth) validated at config-load time\n\n## Getting started\n\nAdd 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 .\n\n```json\n{\n \"mcpServers\": {\n \"ntfy-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"ntfy-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"NTFY_DEFAULT_TOPIC\": \"your-topic-name\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"ntfy-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"-e\", \"NTFY_DEFAULT_TOPIC=your-topic-name\",\n \"ghcr.io/cyanheads/ntfy-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 NTFY_DEFAULT_TOPIC=your-topic bun run start:http\n# Server listens at http://127.0.0.1:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.11](https://bun.sh/) or higher (or Node.js v24+).\n- 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.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/ntfy-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd ntfy-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env and set NTFY_DEFAULT_TOPIC (and auth, if needed)\n```\n\n## Configuration\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `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. | — |\n| `NTFY_BASE_URL` | Single-server shorthand — base URL of the ntfy server (no trailing slash). Used when `NTFY_SERVERS` is unset. | `https://ntfy.sh` |\n| `NTFY_DEFAULT_TOPIC` | Topic used when a tool call omits `topic`. | — |\n| `NTFY_AUTH_TOKEN` | Bearer access token (`tk_…`) for the single-server shorthand. Mutually exclusive with `NTFY_AUTH_USERNAME` / `NTFY_AUTH_PASSWORD`. | — |\n| `NTFY_AUTH_USERNAME` | Basic-auth username for the single-server shorthand — required together with `NTFY_AUTH_PASSWORD`. | — |\n| `NTFY_AUTH_PASSWORD` | Basic-auth password for the single-server shorthand — required together with `NTFY_AUTH_USERNAME`. | — |\n| `NTFY_REQUEST_TIMEOUT_MS` | Per-request HTTP timeout in milliseconds. | `15000` |\n| `NTFY_MAX_RETRIES` | Max retry attempts for transient upstream failures (5xx, network, 429). | `3` |\n| `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` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_SESSION_MODE` | HTTP session model: `auto`, `stateful`, or `stateless`. `auto` resolves to `stateful`. Keep it stateful — 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. | `auto` (→ `stateful`) |\n| `MCP_HTTP_HOST` | HTTP host. | `127.0.0.1` |\n| `MCP_HTTP_PORT` | HTTP port. | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path. | `/mcp` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `LOGS_DIR` | Directory for file-based logs (Node only; ignored on Workers). | `./logs` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (spans, metrics, completion logs). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security, changelog sync\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t ntfy-mcp-server .\ndocker run --rm -e NTFY_DEFAULT_TOPIC=your-topic -p 3010:3010 ntfy-mcp-server\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools and resources, initializes services. |\n| `src/config` | Server-specific environment variable parsing (`NTFY_*`) with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). |\n| `src/services/ntfy` | ntfy HTTP client, types, and error classifier. |\n| `src/services/emoji-tags` | Bundled emoji short-code reference and lookup service. |\n| `docs/ntfy` | Mirrored upstream ntfy API docs (pinned commit in `SOURCES.md`). |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n- Per-tool `errors[]` contracts stay inline — repetition is intended for locality\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 13828,
"sha": "4156daf1b3c4788f31abd198c96c3417a625099cccaa3d30eff5bc1a7848a1cd",
"repo_slug": "cyanheads/ntfy-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_ntfy_mcp_server_46281649/readme"
}