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

Name	Link / Badge
ntfy.sh	Featured on 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!

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

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 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`
MCP Marketplace — Smithery One-command install for Claude Desktop via Smithery.	Show command `npx -y @smithery/cli install @gitmotion/ntfy-me-mcp --client claude`

Setting Up the Notification Receiver

View ntfy receiver Section

Install the ntfy app on your device
- or deploy your own ntfy server: https://docs.ntfy.sh/install/
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.

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

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

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

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

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

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

Version	Changes	Urgency	Date
v1.4.2	## ntfy-me-mcp v1.4.2 ### What's Changed * fix: disregard empty strings for ntfyTopic & priority + README/CONTRIBUTING cleanup by @gitmotion in https://github.com/gitmotion/ntfy-me-mcp/pull/16 \| Input \| Result \| \|--------\|--------\| \| <img width="392" height="374" alt="Image" src="https://github.com/user-attachments/assets/17f023cf-7383-465d-802a-5122128d3207" /> \| <img width="527" height="88" alt="Image" src="https://github.com/user-attachments/assets/7a6bc76a-f1cc-4c02-96ee-243a594d051	High	4/11/2026
v1.4.1	## Minor Dev Update Update publish-docker.yml workflow dockerhub username to vars - allow for proper attestation link and image tags in summary generation - workflow summary: https://github.com/gitmotion/ntfy-me-mcp/actions/runs/24125656035 Full Changelog: https://github.com/gitmotion/ntfy-me-mcp/compare/v1.4.0...v1.4.1	High	4/8/2026
v1.4.0	# ntfy-me-mcp v1.4.0 Release Notes This release delivers a security and maintainability upgrade, addressing prompt-injection risks, improving schema validation, and refactoring the codebase for clarity and testability. ## Highlights - Security Hardening - Strict URL validation for all ntfy server calls (prevents prompt injection via malicious URLs) - Topic validation: only allows alphanumeric, underscore, hyphen (max 128 chars) - Error sanitization: never reflects attacker-	Medium	4/8/2026
v1.3.5	## What's Changed Fixes: * bugfix: print/log to sys.stderr insted of sys.stdout #6 - thanks @michalcamona 🙏🏻 * bugfix: print/log to sys.stderr insted of sys.stdout #7 - thanks @michalcamona 🙏🏻 Enhancements: - introduce logger abstraction, update readme, bump version to v1.3.5, include gh pull request template #8 / #9 - @gitmotion - for any future updates you can just use `logger.info`, `logger.warn`, `logger.error` respectively - internally uses console.error for each method to	Low	8/6/2025
v1.3.1	## What's Changed Documentation Update: * Add MseeP.ai badge by @lwsinclair in https://github.com/gitmotion/ntfy-me-mcp/pull/3 ## New Contributors * @lwsinclair made their first contribution in https://github.com/gitmotion/ntfy-me-mcp/pull/3 Full Changelog: https://github.com/gitmotion/ntfy-me-mcp/compare/v1.3.0...v1.3.1	Low	5/14/2025
v1.3.0	## What's Changed * v1.3.0 includes changes for fetching ntfy notifications using natural language or with the newly specified tool `ntfy_me_fetch`. * [read more in the docs](https://github.com/gitmotion/ntfy-me-mcp?tab=readme-ov-file#retrieving-messages-ntfy_me_fetch-tool) * add MCP server badge by @punkpeye in https://github.com/gitmotion/ntfy-me-mcp/pull/1 * Deployment: Dockerfile and Smithery config by @calclavia in https://github.com/gitmotion/ntfy-me-mcp/pull/2 * v1.2.0 - included c	Low	4/18/2025

ntfy-me-mcp

Description

README

ntfy-me-mcp

Overview

Features

Coming soon...

Table of Contents

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

Development & Contributions

License

Release History

Dependencies & License Audit

Similar Packages

More in MCP Servers

ntfy-me-mcp

Description

README

ntfy-me-mcp

Overview

Features

Coming soon...

Table of Contents

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

Development & Contributions

License

Release History

Dependencies & License Audit

Similar Packages

More in MCP Servers

`ntfy_me`: Sending Notifications

`ntfy_me_fetch`: Polling Notifications