Ntfy MCP Server
by cyanheadsio.github.cyanheads/ntfy-mcp-serverv2.3.6
Send, manage, and replay ntfy push notifications via MCP.
context tax
queued
security
queued
cold start
queued
freshness
Active3d ago
Install Ntfy MCP server
Install in Claude Code
claude mcp add ntfy-cyanheads -- npx -y ntfy-mcp-serverInstall in Cursor
{
"mcpServers": {
"ntfy-cyanheads": {
"command": "npx",
"args": [
"-y",
"ntfy-mcp-server"
]
}
}
}Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).
Install in Claude Desktop
{
"mcpServers": {
"ntfy-cyanheads": {
"command": "npx",
"args": [
"-y",
"ntfy-mcp-server"
]
}
}
}Settings → Developer → Edit Config (claude_desktop_config.json), then restart.
Install in VS Code
{
"servers": {
"ntfy-cyanheads": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"ntfy-mcp-server"
]
}
}
}Add to .vscode/mcp.json in your workspace.
Install in Windsurf
{
"mcpServers": {
"ntfy-cyanheads": {
"command": "npx",
"args": [
"-y",
"ntfy-mcp-server"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json.
Configuration
| Variable | Required | Secret | Description |
|---|---|---|---|
| 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 over the single-server NTFY_BASE_URL / NTFY_AUTH_* shorthand. |
| NTFY_BASE_URL | — | — | 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_MS | — | — | Per-request HTTP timeout in milliseconds. |
| NTFY_MAX_RETRIES | — | — | Max retry attempts for transient upstream failures (5xx, network, 429). |
| 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. Turn it on where callers you do not control can reach the server. |
| MCP_LOG_LEVEL | — | — | Sets the minimum log level for output (e.g., 'debug', 'info', 'warn'). |
| LOGS_DIR | — | — | Directory for file-based logs (Node only; ignored on Workers). |
| OTEL_ENABLED | — | — | Enable OpenTelemetry instrumentation (spans, metrics, completion logs). |
| MCP_TRANSPORT_TYPE | — | — | Selects the HTTP transport. |
| 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. |
| MCP_HTTP_HOST | — | — | The hostname for the HTTP server. |
| MCP_HTTP_PORT | — | — | The port to run the HTTP server on. |
| MCP_HTTP_ENDPOINT_PATH | — | — | The endpoint path for the MCP server. |
| MCP_AUTH_MODE | — | — | Authentication mode to use: 'none', 'jwt', or 'oauth'. |
| MCP_REQUEST_STATE_KEY | — | yes | 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. |
Freshness
Active — last maintenance signal 3d ago. The newest of the signals below sets the band.
Last commit (default branch)
2026-10-07 · 3d ago · GitHub
Latest release
2026-10-07 · 3d ago · GitHub · v2.3.6
Package published
no data · npm/PyPI
Registry entry updated
2026-10-07 · 3d ago · official registry · v2.3.6
FAQ
›How do I install the Ntfy MCP server in Claude Code?
Run: claude mcp add ntfy-cyanheads -- npx -y ntfy-mcp-server. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.
›Does Ntfy require an API key?
Yes. It expects MCP_REQUEST_STATE_KEY, of which 1 is a secret.
›Can I use Ntfy as a remote (hosted) MCP server?
Yes — it offers both a hosted endpoint and a local stdio package.
›Is Ntfy in the official MCP registry?
Yes, as io.github.cyanheads/ntfy-mcp-server.