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 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

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, a self-hosted, open-source AI agent platform, reports that ntfy-me-mcp works with it and lists it among its 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

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "$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"
      }
    }
  }
}

{
  "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:-}"
      }
    }
  }
}

{
  "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": ["*"]
    }
  }
}

[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"

    </details>
  </td>
</tr>
<tr>
  <td>Token Auth</td>
  <td>Required for protected topics or self-hosted servers. See <a href="#secure-token-handling-vscode">Secure Token Handling (vscode)</a> or set <code>NTFY_TOKEN</code> directly.</td>
  <td>
    <details>
      <summary>Show config</summary>
      <pre><code>{

Installation

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

# 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

Configuration

Environment Variables

Create a .env file by copying the example: cp .env.example .env — see .env.example for reference.

Authentication

// 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}"
      }
    }
  }
}

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

{
  "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

{
  title: "Task Complete",
  message: "Regular plain text message",
  markdown: false  // Force disable
}

{
  title: "Build Complete",
  message: "View at https://github.com/org/repo/pull/123"
}

{
  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
    }
  ]
}

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

{
  "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

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).

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": "<message>" }. 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).
• 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).
  • 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). 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 rather than in a public issue.

Development & Contributions

Contributions are welcome! Please see 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 file for details.

Made with ❤️ by gitmotion