ntfy-me-mcp

> A streamlined Model Context Protocol (MCP) server for sending notifications via ntfy service (public or selfhosted 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

NameLink / Badge

ntfy.sh

Glama.ai

Smithery.ai

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
• 📄 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)
• 🔗 Click urls: Ability to customize click urls
• 🖼️ 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

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.

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"

}

}

}

}

ClaudeCode

Add to .mcp.json at your project root (shared with your team via version control), or to ~/.claude.json for user-level access across all projects.

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

}

}

}

Token Auth

Required for protected topics or self-hosted servers. See 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 globallyInstall once, run anywhere with the ntfy-me-mcp command.

npm install -g ntfy-me-mcp

Run with npxNo install needed — ideal for a quick one-off run or testing.

npx ntfy-me-mcp

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

MCP Marketplace — SmitheryOne-command install for Claude Desktop via .

Show command

npx -y @smithery/cli install @gitmotion/ntfy-me-mcp --client claude

Setting Up the Notification Receiver

View ntfy receiver Section

1. Install the ntfy app on your device

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` for reference.

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

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

> If the client resolves `"${input:ntfy_token}"` before launch, the server receives the real token directly. If the placeholder is passed through unchanged, ntfy-me-mcp detects that unresolved input reference and prompts for the token itself at startup.

>

> Since `v1.4.0+`, the `PROTECTED_TOPIC` env has been removed. This handling is now auto-detected from the unresolved `NTFY_TOKEN` input reference 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

{

"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

Yes

—

message

The notification body

Yes

—

url

Custom ntfy server URL

No

Default: NTFY_URL

topic

Custom ntfy topic

No

Default: NTFY_TOPIC

accessToken

Access token for protected topics

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 .

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. URLs in the message body are auto-detected (up to 3 actions). For manual control, each action requires action, label, and url, 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

}

]

}

`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"
"Check my latest alerts"

Example Usage

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

}

]

}

}

Fetch Parameters

Parameter

Description

Required

Details / Example

url

Custom ntfy server URL

No

Default: NTFY_URL

topic

Topic to fetch messages from

No

Default: NTFY_TOPIC{ "topic": "updates", "since": "all" }

accessToken

Access token for protected topics

No

Default: NTFY_TOKEN

since

How far back to retrieve messages

No

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

No

{ "priorities": "high" }

tags

Find messages with specific tags

No

{ "tags": ["error", "warning"] }

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