ntfy-me-mcp [![TypeScript](https://img.shields.io/npm/dependency-version/ntfy-me-mcp/dev/typescript?logo=typescript&label=TypeScript&color=blue)](https://www.typescriptlang.org/) [![Model Context Protocol](https://img.shields.io/npm/dependency-version/ntfy-me-mcp/@modelcontextprotocol/sdk?logo=anthropic&label=MCP%20SDK&color=green)](https://modelcontextprotocol.io/) [![NPM Version](https://img.shields.io/npm/v/ntfy-me-mcp.svg?logo=npm&color=orange)](https://www.npmjs.com/package/ntfy-me-mcp) [![Docker Image Version](https://img.shields.io/docker/v/gitmotion/ntfy-me-mcp?logo=docker&label=Docker)](https://hub.docker.com/r/gitmotion/ntfy-me-mcp) [![License](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](LICENSE) [![GitHub](https://img.shields.io/github/stars/gitmotion/ntfy-me-mcp?style=social)](https://github.com/gitmotion/ntfy-me-mcp)

> A streamlined Model Context Protocol (MCP) server for sending and fetching notifications via the ntfy service (public or self-hosted, with token support) 📲 ## Overview ntfy-me-mcp provides AI assistants with the ability to send real-time notifications to your devices through the [ntfy.sh](https://ntfy.sh) service (either public or selfhosted with token support). Get notified when your AI completes tasks, encounters errors, or reaches important milestones - all without constant monitoring. The server includes intelligent features like automatic URL detection for creating view actions and smart markdown formatting detection, making it easier for AI assistants to create rich, interactive notifications without extra configuration.

Preview

Available via

Name	Link / Badge
ntfy.sh	Featured on ntfy.sh
Glama.ai
LightNow
MseeP.ai
Archestra.ai

## Features - 🚀 **Quick Setup**: Run with npx or docker! - 🔔 **Real-time Notifications**: Get updates on your phone/desktop when tasks complete - 🎨 **Rich Notifications**: Support for topic, title, priorities, emoji tags, and detailed messages - 🔍 **Notification Fetching**: Fetch and filter cached messages from your ntfy topics - 🎯 **Smart Action Links**: Automatically detects URLs in messages and creates view actions - 🔗 **Click URLs**: Choose the link that opens when the notification is tapped - 📄 **Intelligent Markdown**: Auto-detects and enables markdown formatting when present - 🔒 **Secure**: Optional authentication with access tokens - 🔑 **Input Masking**: Securely store your ntfy token in your vs config! - 🌐 **Self-hosted Support**: Works with both ntfy.sh and self-hosted ntfy instances #### Coming soon... - 📨 **Email**: Send notifications to email (requires ntfy email server configuration) - 🖼️ **Image urls**: Intelligent image url detection to automatically include image urls in messages and notifications - 🏁 and more! ## Table of Contents

Section	Topics
Quickstart - MCP Server Configuration	Configuration Examples
Installation	Setting Up the Notification Receiver
Configuration	Environment Variables Authentication ↳ Secure Token Handling (vscode)
Tools & Usage	ntfy_me: Sending Notifications ↳ Using Natural Language ↳ Example Usage ↳ Message Parameters ntfy_me_fetch: Polling Notifications ↳ Using Natural Language ↳ Example Usage ↳ Fetch Parameters Tool output
Security
Development & Contributions
License

## Quickstart - MCP Server Configuration Choose the config shape that matches your client. All examples below use `NTFY_TOPIC` as the required variable and keep the optional auth settings commented out until you need them. > **Tested with Ontheia:** [Ontheia](https://ontheia.ai), a self-hosted, open-source AI agent platform, reports that ntfy-me-mcp works with it and lists it among its [compatible MCP servers](https://docs.ontheia.ai/en/getting-started/03_compatible-mcp-servers/). > **Requirements:** Node.js 24 or newer for the npx, global and local options. CI and the Docker image use Node 24. Node 22 and earlier aren't supported (npm warns `EBADENGINE`). The Docker option needs only Docker. ### Configuration Examples

Type	Use Case	Example
NPM / NPX	Recommended for most MCP clients when you want the lightest setup.	Show config `{ "ntfy-me-mcp": { "command": "npx", "args": ["-y", "ntfy-me-mcp"], "env": { "NTFY_TOPIC": "your-ntfy-topic", "NTFY_URL": "https://ntfy.sh", // "NTFY_TOKEN": "add-your-ntfy-token" } } }`
Local	Use a local checkout when you are developing or changing the server yourself. Replace `/absolute/path/to/ntfy-me-mcp/build/index.js` after building.	Show config `{ "ntfy-me-mcp": { "command": "node", "args": ["/absolute/path/to/ntfy-me-mcp/build/index.js"], "env": { "NTFY_TOPIC": "your-ntfy-topic", "NTFY_URL": "https://ntfy.sh", // "NTFY_TOKEN": "add-your-ntfy-token" } } }`
Docker	Use a containerized setup when Docker is already part of your environment. - DockerHub: `gitmotion/ntfy-me-mcp:latest` - GHCR: `ghcr.io/gitmotion/ntfy-me-mcp:latest`	Show config `{ "ntfy-me-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "NTFY_TOPIC", "-e", "NTFY_URL", "-e", "NTFY_TOKEN", "gitmotion/ntfy-me-mcp:latest" ], "env": { "NTFY_TOPIC": "your-ntfy-topic", "NTFY_URL": "https://ntfy.sh", // "NTFY_TOKEN": "add-your-ntfy-token" } } }`
OpenCode	Add to `opencode.json` in your project root (for project-level config) or `~/.config/opencode/opencode.json` (for global config). Uses `"mcp"` as the top-level key with `type: "local"` and `command` as an array.	Show config `{ "$schema": "https://opencode.ai/config.json", "mcp": { "ntfy-me-mcp": { "type": "local", "command": ["npx", "-y", "ntfy-me-mcp"], "environment": { "NTFY_TOPIC": "your-ntfy-topic", "NTFY_URL": "https://ntfy.sh", // "NTFY_TOKEN": "add-your-ntfy-token" } } } }`
Claude Code	Quickest: run `claude mcp add ntfy-me-mcp -e NTFY_TOPIC=your-ntfy-topic -- npx -y ntfy-me-mcp` (add `--scope user` for all projects, or `--scope project` to write `.mcp.json`). Or add it by hand to `.mcp.json` at your project root (shared with your team via version control). `${NTFY_TOKEN:-}` reads the token from your shell environment and falls back to empty.	Show config `{ "mcpServers": { "ntfy-me-mcp": { "command": "npx", "args": ["-y", "ntfy-me-mcp"], "env": { "NTFY_TOPIC": "your-ntfy-topic", "NTFY_URL": "https://ntfy.sh", "NTFY_TOKEN": "${NTFY_TOKEN:-}" } } } }`
Copilot CLI	Add to `~/.copilot/mcp-config.json` for user-level access across all sessions. Use `type: "local"` for stdio-based servers like this one.	Show config `{ "mcpServers": { "ntfy-me-mcp": { "type": "local", "command": "npx", "args": ["-y", "ntfy-me-mcp"], "env": { "NTFY_TOPIC": "your-ntfy-topic", "NTFY_URL": "https://ntfy.sh", "NTFY_TOKEN": "your-access-token" }, "tools": ["*"] } } }`
Codex	Run `codex mcp add ntfy-me-mcp --env NTFY_TOPIC=your-ntfy-topic -- npx -y ntfy-me-mcp`, or add the block to `~/.codex/config.toml` by hand.	Show config `[mcp_servers.ntfy-me-mcp] command = "npx" args = ["-y", "ntfy-me-mcp"] [mcp_servers.ntfy-me-mcp.env] NTFY_TOPIC = "your-ntfy-topic" NTFY_URL = "https://ntfy.sh" # NTFY_TOKEN = "your-access-token"`
Token Auth	Required for protected topics or self-hosted servers. See Secure Token Handling (vscode) or set `NTFY_TOKEN` directly.	Show config `{ "ntfy-me-mcp": { "command": "npx", "args": ["-y", "ntfy-me-mcp"], "env": { "NTFY_TOPIC": "your-ntfy-topic", "NTFY_URL": "https://your-ntfy-server.com", "NTFY_TOKEN": "your-access-token" } } }`

## Installation If you need to install and run the server directly (alternative to the MCP configuration above):

Option	Example
Install globally Install once, run anywhere with the `ntfy-me-mcp` command.	`npm install -g ntfy-me-mcp`
Run with npx No install needed — ideal for a quick one-off run or testing.	`npx ntfy-me-mcp`
Install locally Clone the repo, install deps, build, and run via `npm start`.	Show steps `# Clone repo, install deps, configure .env, build, run git clone https://github.com/gitmotion/ntfy-me-mcp.git cd ntfy-me-mcp npm install cp .env.example .env npm run build npm start`

### Setting Up the Notification Receiver

View ntfy receiver Section

1. Install the [ntfy app](https://ntfy.sh/app) on your device - or deploy your own ntfy server: https://docs.ntfy.sh/install/ 2. Subscribe to your chosen topic (the same as your `NTFY_TOPIC` setting)

## Configuration ### Environment Variables Create a `.env` file by copying the example: `cp .env.example .env` — see [`.env.example`](.env.example) for reference. | Variable | Required | Default | Description | | --- | --- | --- | --- | | `NTFY_TOPIC` | Yes | — | The ntfy topic to publish notifications to | | `NTFY_URL` | No | `https://ntfy.sh` | ntfy server URL — change this for self-hosted instances
(include port if needed, e.g. `https://your-server.com:8443`) | | `NTFY_TOKEN` | No | — | Access token for protected topics or private servers. Only ever sent to the `NTFY_URL` server | | `NTFY_ALLOW_TOPIC_OVERRIDE` | No | `false` | Set to `true` to let the agent choose a per-call `topic`. When off (the default), the `topic` parameter isn't offered to the agent and every notification and fetch uses `NTFY_TOPIC` | | `NTFY_TOPICS_ALLOWLIST` | No | — | Comma-separated topics you subscribe to, e.g. `alerts,builds,deploys`. When set, the agent may send to or fetch from `NTFY_TOPIC` or one of these topics, and no other topic. The `topic` parameter is offered as a list of exactly those topics. Takes precedence over `NTFY_ALLOW_TOPIC_OVERRIDE`. An invalid entry, or a value that lists no topics (e.g. `,`), stops the server at startup | | `NTFY_ALLOW_URL_OVERRIDE` | No | `false` | Set to `true` to let the agent choose a per-call server `url`. When off (the default), the `url` parameter isn't offered and every request goes to `NTFY_URL`. Even when on, `NTFY_TOKEN` is only sent to `NTFY_URL` | ### Authentication

View Authentication Section

This MCP server supports both authenticated and unauthenticated ntfy endpoints: - **Public Topics**: When using public topics on ntfy.sh or other public servers, no authentication is required. - **Protected Topics**: - For protected topics or private servers, you need to provide an access token via `NTFY_TOKEN` env variable or in the `accessToken` parameter of the tool. - If authentication is required but not provided, you'll receive a clear error message explaining how to add your token. #### Secure Token Handling (vscode) - If your client supports prompt-based secret inputs (i.e. VS Code), prefer that over hardcoding `NTFY_TOKEN` in config files. (Otherwise use your token directly) - Use matching values like this in your `mcp.json` file:

Show VS Code mcp.json example

```jsonc // Add this to your VS Code `mcp.json` file, either the user-level file or your workspace `.vscode/mcp.json` // Set `NTFY_TOKEN` exactly to `"${input:ntfy_token}"` when you want VS Code to treat it as a secure prompt-backed value. { "inputs": [ { "type": "promptString", "id": "ntfy_token", "description": "Ntfy Token", "password": true } ], "servers": { "ntfy-me-mcp": { "command": "npx", "args": ["-y", "ntfy-me-mcp"], "env": { "NTFY_TOPIC": "your-ntfy-topic", "NTFY_URL": "https://your-ntfy-server.com", "NTFY_TOKEN": "${input:ntfy_token}" } } } } ```

| Field | Value | Purpose | | --- | --- | --- | | `env.NTFY_TOKEN` | `"${input:ntfy_token}"` | References the secure prompt-backed token value | | `inputs[].id` | `"ntfy_token"` | Defines the input name used by `NTFY_TOKEN` | | `inputs[].type` | `"promptString"` | Prompts the user for the token at runtime | > Your MCP client must resolve `"${input:ntfy_token}"` before it launches the server, as VS Code does, so the server receives the real token. If your client doesn't support `${input:…}` references (Claude Desktop, Claude Code, Codex and others), set `NTFY_TOKEN` to the real token or to an environment-variable reference your client does support. If the placeholder reaches the server unresolved, the server can't ask you for the token (stdin and stdout carry the MCP connection), so it exits at startup with an error saying `NTFY_TOKEN is an unresolved ${input:…} reference`, which your client shows in its MCP server log. The same goes for any other placeholder your client didn't substitute, such as `${env:NTFY_TOKEN}` or `${NTFY_TOKEN}`: the server exits with `NTFY_TOKEN contains an unresolved ${…} placeholder` instead of sending it as a token, which ntfy servers with auth enabled (such as ntfy.sh) reject on every request. > > The `PROTECTED_TOPIC` env var was removed in `v1.4.0`. For protected topics, set `NTFY_TOKEN`, resolved by your client, instead.

## Tools & Usage ### `ntfy_me`: Sending Notifications #### Using Natural Language - When working with your AI assistant, you can use natural phrases to request notifications: ``` "ntfyme with a summary of the task when complete" "Send me a notification when the build is complete" "Notify me when the task is done" "Alert me after generating the code" "Message me when the process finishes" "Send an alert with high priority" ``` #### Example Usage

Input Output

Input	Output
`{ "title": "Code Generation Complete", "message": "Your React component has been created successfully with proper TypeScript typing.", "priority": "high", "tags": ["white_check_mark", "code", "react"] }`	`{ "success": true, "endpoint": "https://ntfy.sh/ntfymetest" }`

{
  "title": "Code Generation Complete",
  "message": "Your React component has been
created successfully with proper
TypeScript typing.",
  "priority": "high",
  "tags": ["white_check_mark", "code", "react"]
}

{
  "success": true,
  "endpoint": "https://ntfy.sh/ntfymetest"
}

#### Message Parameters

Parameter	Description	Required	Details / Example
`title`	The notification title. Unicode and emoji are supported	Yes	—
`message`	The notification body	Yes	—
`url`	Custom ntfy server URL. Only offered when `NTFY_ALLOW_URL_OVERRIDE=true`. `NTFY_TOKEN` is only sent to the `NTFY_URL` server; pass `accessToken` for another server	No	Default: `NTFY_URL`
`topic`	Custom ntfy topic. Only offered when `NTFY_TOPICS_ALLOWLIST` is set (then limited to `NTFY_TOPIC` and those topics) or `NTFY_ALLOW_TOPIC_OVERRIDE=true`; otherwise every notification goes to `NTFY_TOPIC`	No	Default: `NTFY_TOPIC`
`accessToken`	Access token for protected topics. A blank value (`""`, spaces) counts as not provided	No	Default: `NTFY_TOKEN`
`priority`	Message priority level	No	Default: `"default"` Options: `min`, `low`, `default`, `high`, `max`
`tags`	Array of notification tags. Supports emoji shortcodes for visual indicators — see the full list.	No	`warning` → ⚠️ `white_check_mark` → ✅ `rocket` → 🚀 `tada` → 🎉
`markdown`	Boolean to enable markdown formatting. Auto-detected when markdown syntax is present (headers, lists, code blocks, links, bold/italic) — no need to set explicitly. Can be overridden manually.	No	Auto-detection: no configuration needed. Manual override example `{ title: "Task Complete", message: "Regular plain text message", markdown: false // Force disable }`
`actions`	Array of view action objects for clickable links (at most 3 per notification). URLs in the message body are auto-detected (up to 3 actions). For manual control, each action requires `action`, `label`, and an `http://` or `https://` `url` without embedded credentials, with an optional `clear` flag.	No	Auto-detection example `{ title: "Build Complete", message: "View at https://github.com/org/repo/pull/123" }` Automatically creates view actions for detected URLs. Manual configuration example `{ title: "Pull Request Review", message: "Ready for final checks", actions: [ { action: "view", label: "View PR", url: "https://github.com/org/repo/pull/123" }, { action: "view", label: "View Changes", url: "https://github.com/org/repo/pull/123/files", clear: true } ] }`
`click`	Link opened when the notification itself is tapped (ntfy's click action). Must be `http://`, `https://`, `mailto:`, `geo:` or `ntfy://`, without embedded credentials. A blank value counts as not provided	No	`{ "click": "https://github.com/user/repo/actions/runs/123" }`

### `ntfy_me_fetch`: Polling Notifications #### Using Natural Language AI assistants understand various ways to request message fetching: ``` "Show me my recent notifications" "Get messages from the last hour" "Find notifications with title 'Build Complete'" "Search for messages with the test_tube tag" "Show notifications from the updates topic from the last 24hr" # needs updates in NTFY_TOPICS_ALLOWLIST (or NTFY_ALLOW_TOPIC_OVERRIDE=true) "Check my latest alerts" ``` #### Example Usage

Input Output

Input	Output
`{ "since": "6h" }`	`{ "success": true, "messageCount": 1, "topics": { "ntfymetest": [ { "id": "On4Jeo1ENDCB", "time": 1775859291, "event": "message", "topic": "ntfymetest", "message": "Test", "title": "Test", "priority": 3, "expires": 1775902491 } ] } }`

{
  "since": "6h"
}

{
  "success": true,
  "messageCount": 1,
  "topics": {
    "ntfymetest": [
      {
        "id": "On4Jeo1ENDCB",
        "time": 1775859291,
        "event": "message",
        "topic": "ntfymetest",
        "message": "Test",
        "title": "Test",
        "priority": 3,
        "expires": 1775902491
      }
    ]
  }
}

#### Fetch Parameters

Parameter	Description	Required	Details / Example
`url`	Custom ntfy server URL. Only offered when `NTFY_ALLOW_URL_OVERRIDE=true`. `NTFY_TOKEN` is only sent to the `NTFY_URL` server; pass `accessToken` for another server	No	Default: `NTFY_URL`
`topic`	Topic to fetch messages from. Only offered when `NTFY_TOPICS_ALLOWLIST` is set (limited to `NTFY_TOPIC` and those topics) or `NTFY_ALLOW_TOPIC_OVERRIDE=true`	No	Default: `NTFY_TOPIC` `{ "topic": "updates", "since": "all" }`
`accessToken`	Access token for protected topics. A blank value (`""`, spaces) counts as not provided	No	Default: `NTFY_TOKEN`
`since`	How far back to retrieve messages	No	Default: `"10m"` Options: `'10m'`, `'1h'`, `'1d'`, timestamp, message ID, or `'all'` Example: `{ "since": "30m" }`
`messageId`	Find a specific message by its ID	No	`{ "messageId": "xxxxXXXXxxxx" }`
`messageText`	Find messages containing exact text content	No	`{ "messageText": "Build Complete" }`
`messageTitle`	Find messages with exact title/subject	No	`{ "messageTitle": "Build Complete", "priorities": "high", "since": "1d" }`
`priorities`	Find messages with specific priority levels. A single value or an array.	No	`{ "priorities": "high" }` `{ "priorities": ["high", "max"] }`
`tags`	Find messages with specific tags. A single tag or an array; every listed tag must be present.	No	`{ "tags": "error" }` `{ "tags": ["error", "warning"] }`

### Tool output Both tools return human-readable `content` for the model and a machine-readable `structuredContent` object. For `ntfy_me_fetch`, `content` also includes the fetched messages as JSON. That text comes from whoever published to the topic, so treat it as untrusted (see [Security](#security)). | Tool | Success (`structuredContent`) | | --- | --- | | `ntfy_me` | `{ "success": true, "endpoint": "https://ntfy.sh/your-topic" }` | | `ntfy_me_fetch` | `{ "success": true, "messageCount": 1, "topics": { "your-topic": [ /* messages */ ] } }`
When the server returns an empty response (no cached messages in the requested window): `{ "success": true, "topic": "your-topic", "messages": [] }`
When the response contains no valid message records: `{ "success": true, "messageCount": 0, "topics": {} }` | **Invalid arguments** (a missing `title`, a malformed `topic`, an unknown `priority`, …) are rejected by the MCP SDK's schema validation before the tool runs. They come back with `isError: true` and a text-only `MCP error -32602: Input validation error: …` message that names the field and the expected format, with no `structuredContent`. **Failures inside the tool** set `isError: true` and return `{ "success": false, "error": "" }`. The error message is specific for an invalid `url` or `topic`, an authentication failure (HTTP 401/403), a non-2xx status code (`... Status code: 500`), or a network failure, named with Node's error code: `... could not connect to the ntfy server (ECONNREFUSED)` when no connection was made, or `... the request to the ntfy server failed (ECONNRESET)` when it broke after connecting (the notification may have been delivered). Anything else is reported generically (`Failed to send ntfy notification` / `Failed to fetch ntfy messages`), so raw input or server text is never echoed back to the model. The full underlying error is written to the server's stderr log. ## Security ntfy-me-mcp treats every tool argument as untrusted, because it comes from a model that may have read prompt-injected content. - **URLs:** only `http://` and `https://` server URLs are accepted, from both the `url` argument and `NTFY_URL`. URLs with embedded credentials (`https://user:pass@…`) are rejected; use `NTFY_TOKEN` or `accessToken`. - **Startup checks:** a missing or invalid `NTFY_TOPIC`, or an invalid `NTFY_URL` (not http(s), or containing `user:pass@`), stops the server at startup. The error names the variable and is written to stderr, which your MCP client shows in its server log. The server checks these before logging `NTFY_URL`, so embedded credentials never reach the log. - **Tokens and logs:** access tokens must be printable ASCII without spaces. Errors are written to stderr with bearer values and URL credentials redacted. - **Topics:** letters, numbers, `_` and `-` only, up to 128 characters. - **Error messages:** only a fixed set of known-safe messages reaches the model. Everything else is replaced with a generic message, so attacker-controlled text is never reflected back (see [#13](https://github.com/gitmotion/ntfy-me-mcp/issues/13)). - **Fetched messages are untrusted input.** `ntfy_me_fetch` hands message content to the model, and anyone who knows a public topic's name can publish to it. On ntfy.sh, use a hard-to-guess topic name, or a protected topic with an access token. - **Destination control:** by default, every notification and fetch goes to `NTFY_TOPIC` on `NTFY_URL`. The agent is never offered the `topic` or `url` parameters, so a prompt-injected call can't send your messages, or your topic name (which is effectively a password on public ntfy.sh), anywhere else (see [#21](https://github.com/gitmotion/ntfy-me-mcp/issues/21)). - `NTFY_TOPICS_ALLOWLIST=alerts,builds` lets the agent choose among the topics you actually subscribe to, plus `NTFY_TOPIC`, and no other topic (see [#34](https://github.com/gitmotion/ntfy-me-mcp/issues/34)). Any other topic is rejected before a request is made, with no silent fallback. These topic names, **including `NTFY_TOPIC`**, appear in the tool schema, so the model and your MCP client can see them. Without an allowlist, the tool schema never contains a topic name. On public ntfy.sh, a topic name works like a password, so only use the allowlist with names you're comfortable sharing with them, or with protected topics. - `NTFY_ALLOW_TOPIC_OVERRIDE=true` and `NTFY_ALLOW_URL_OVERRIDE=true` opt back in to any topic or server, independently. If `NTFY_TOPICS_ALLOWLIST` is also set, it wins over `NTFY_ALLOW_TOPIC_OVERRIDE`. - Even with url overrides on, `NTFY_TOKEN` is only ever sent to the `NTFY_URL` server. Other servers get no credentials unless the call supplies its own `accessToken`. - **Tokens:** prefer your client's secret input (e.g. VS Code `${input:…}`) or an environment variable over hardcoding `NTFY_TOKEN` in a config file you share. Found a vulnerability? Please report it privately through [GitHub security advisories](https://github.com/gitmotion/ntfy-me-mcp/security/advisories/new) rather than in a public issue. ## Development & Contributions Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md), which include general guidelines, setup steps, etc. ## License This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details. --- Made with ❤️ by [gitmotion](https://github.com/gitmotion)