Enables sending notifications to any device with ntfy integration, supporting rich message formatting with titles, tags, priorities, action buttons, and attachments for real-time notifications to phones, desktops, and other devices.
Ntfy MCP Server
An MCP (Model Context Protocol) server designed to interact with the ntfy push notification service. It enables LLMs and AI agents to send notifications to your devices with extensive customization options.
Table of Contents
Overview
This server implements the Model Context Protocol (MCP), enabling standardized communication between LLMs and external systems. Specifically, it provides an interface to the ntfy push notification service.
Ntfy is a simple HTTP-based pub-sub notification service that allows you to send notifications to your phone or desktop via simple HTTP requests. With this MCP server, LLM agents like Claude can send notifications to you through ntfy without needing direct HTTP access.
Features
MCP Server Implementation: Built using the
@modelcontextprotocol/sdk
for seamless integration with LLM agents.Ntfy Integration: Provides a tool (
send_ntfy
) to send notifications with support for:Message prioritization (1-5 levels)
Emoji tags
Clickable actions and buttons
File attachments
Delayed delivery
Markdown formatting
Resource Exposure: Exposes the configured default ntfy topic as an MCP resource.
TypeScript: Modern, type-safe codebase with comprehensive type definitions.
Structured Logging: Uses
winston
andwinston-daily-rotate-file
for detailed and rotatable logs.Configuration Management: Uses
dotenv
for easy environment-based configuration.Utility Scripts: Includes scripts for cleaning build artifacts and generating directory structure documentation.
Error Handling & Security: Implements robust error handling, input sanitization (
sanitize-html
), and security filters (xss-filters
).
Quick Start
Prerequisites:
Node.js (v16+)
npm or yarn
An MCP-compatible client (Claude Desktop, Cline, etc.)
Install and Run:
# Option 1: Install via npm npm install -g ntfy-mcp-server # Option 2: Clone repository and build git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server npm install npm run build # Create .env file (optional but recommended) cp .env.example .env # Edit .env to set NTFY_DEFAULT_TOPIC # Start the server npm startAdd to MCP Client Settings: Add the server to your MCP client settings file (see Configuration)
Use the tool: Once connected, you can use the
send_ntfy
tool to send notifications.
Installation
Option 1: NPM Package (Recommended)
Install the package globally:
npm install -g ntfy-mcp-serverThis will install the server globally, making it available as a command-line tool.
Or install locally in your project:
npm install ntfy-mcp-serverWhen installed locally, you can run it via npx or from node.
Option 2: From Source
Clone the repository:
git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-serverInstall dependencies:
npm installBuild the project:
npm run build
Configuration
Environment Variables
Create a .env
file in the project root based on .env.example
:
MCP Client Settings
For Cline VSCode Extension
Add the following configuration to your Cline MCP settings file (usually located at ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
on macOS):
If installed globally:
If installed from source:
For Claude Desktop App
Add the following configuration to your Claude Desktop config file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json
on macOS):
If installed globally:
If installed from source:
For source installation, replace Adjust
Ntfy Setup
Install the ntfy app on your devices from ntfy.sh or the app stores
Subscribe to your topic in the app
Use the same topic in your MCP server configuration
Project Structure
Tools
send_ntfy
Sends a notification message via the ntfy service.
Key Arguments:
Parameter | Type | Required | Description |
| string | Yes | The ntfy topic to publish to. |
| string | Yes | The main content of the notification (max 4096 bytes). |
| string | No | Notification title (max 250 bytes). |
| string[] | No | Emojis or keywords for categorization (e.g.,
). Max 5. |
| integer | No | Message priority: 1=min, 2=low, 3=default, 4=high, 5=max. |
| string | No | URL to open when the notification is clicked. |
| array | No | Action buttons (view, http, broadcast). Max 3. |
| object | No | URL and name of an attachment. |
| string | No | Email address to forward the notification to. |
| string | No | Delay delivery (e.g.,
,
,
). |
| string | No | Cache duration (e.g.,
,
,
). |
| string | No | Firebase Cloud Messaging (FCM) topic to forward to. |
| string | No | Unique ID for the message. |
| string | No | Message expiration (e.g.,
,
,
). |
| boolean | No | Set to
to enable markdown formatting in the message. |
| string | No | Override the default ntfy server URL for this request. |
Example Usage:
Example Response:
Resources
Direct Resources
ntfy://default
Description: Returns the default ntfy topic configured in the server's environment variables (
NTFY_DEFAULT_TOPIC
).Usage: Useful for clients to discover the primary topic without needing prior configuration.
Example: An LLM agent can access this resource to automatically use the default topic when sending notifications.
Example Response:
{ "defaultTopic": "ATLAS", "timestamp": "2025-03-27T08:30:25.619Z", "requestUri": "ntfy://default", "requestId": "0da963d0-30e0-4dbc-bb77-4bf2dee14484" }
Resource Templates
ntfy://{topic}
Description: Returns information about a specific ntfy topic.
Parameters:
topic
- The name of the ntfy topic.Usage: For querying information about topics other than the default.
Example Response:
{ "topic": "ATLAS", "timestamp": "2025-03-27T08:30:30.038Z", "requestUri": "ntfy://ATLAS", "requestId": "31baf1df-278f-4fdb-860d-019f156a72b0" }
Use Cases
Long-running Task Notifications - Get notified when tasks like database backups, code generation, or data processing complete.
Scheduled Reminders - Set delayed notifications for future events or reminders.
Alert Systems - Set up critical alerts for monitoring systems or important events.
Mobile Notifications from LLMs - Allow LLMs to send notifications directly to your phone.
Multi-step Process Updates - Receive updates as different stages of a complex process complete.
Usage Examples
Basic Notification
Rich Notification with Actions
Available Scripts
npm run build
: Compiles the TypeScript source code to JavaScript in thedist/
directory.npm run clean
: Removes thedist/
directory and cleans the contents of thelogs/
directory.npm run rebuild
: Runsclean
and thenbuild
.npm run tree
: Generates a directory tree representation indocs/tree.md
.npm start
: Runs the compiled server from thedist/
directory using Node.js.npm run watch
: Tails the combined log file (logs/combined.log
) for real-time monitoring.
Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues to improve the project.
Fork the repository.
Create a feature branch (
git checkout -b feature/your-feature
).Commit your changes (
git commit -m 'Add some feature'
).Push to the branch (
git push origin feature/your-feature
).Create a new Pull Request.
For bugs and feature requests, please create an issue on the repository.
Development Best Practices
Follow TypeScript best practices and maintain strong typing
Write tests for new functionality
Keep dependencies up to date
Follow the existing code style and patterns
License
This project is licensed under the Apache-2.0 License. See the LICENSE file for details.
Acknowledgements
ntfy.sh for providing the notification service
Model Context Protocol for enabling LLM-to-tool connections
All contributors and users of this project
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server enabling AI systems to send real-time notifications to phones, desktops, and other devices through the ntfy publish/subscribe service.
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol implementation that enables AI agents to send notifications through Pushover.net, supporting message customization with various parameters like priority, sound, and URL.Last updated -2328MIT License
- -securityAlicense-qualityThe MCP server that keeps you informed by sending the notification on phone using ntfy.shLast updated -140Apache 2.0
- AsecurityAlicenseAqualityA streamlined MCP server that enables AI assistants to send real-time notifications to your devices through the ntfy service, allowing you to receive alerts when tasks complete or important events occur.Last updated -15741GPL 3.0
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI tools to interact with TabNews, providing capabilities to fetch content, comments, analytics, and RSS feeds through natural language.Last updated -93MIT License