Ntfy Me MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Ntfy Me MCP listing page.
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 | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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
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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| Token Auth | Required for protected topics or self-hosted servers. See Secure Token Handling (vscode) or set NTFY_TOKEN directly. |
Show config |
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 |
| MCP Marketplace — Smithery One-command install for Claude Desktop via Smithery. |
Show command |
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_TOPICsetting)
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_TOKENenv variable or in theaccessTokenparameter of the tool. - If authentication is required but not provided, you'll receive a clear error message explaining how to add your token.
- For protected topics or private servers, you need to provide an access token via
Secure Token Handling (vscode)
- If your client supports prompt-based secret inputs (i.e. VS Code), prefer that over hardcoding
NTFY_TOKENin config files. (Otherwise use your token directly) - Use matching values like this in your
mcp.jsonfile:
Show VS Code mcp.json example
| 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+, thePROTECTED_TOPICenv has been removed. This handling is now auto-detected from the unresolvedNTFY_TOKENinput 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:
Example Usage
| Input | Output |
|---|---|
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 |
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 exampleAutomatically creates view actions for detected URLs.Manual configuration example |
ntfy_me_fetch: Polling Notifications
Using Natural Language
AI assistants understand various ways to request message fetching:
Example Usage
| Input | Output |
|---|---|
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