ntfy-me-mcp provides AI assistants with the ability to send real-time notifications to your devices through the ntfy 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
Add this skill
npx mdskills install gitmotion/ntfy-me-mcpWell-documented MCP server enabling real-time notifications via ntfy with smart auto-detection features
1# <img src="https://m2tg1pnwn0.ufs.sh/f/GMqNN8nd9I8l9tUbmif1CnFX8Baqr7mHeicYu0AULDyNVWJE" width=30 /> ntfy-me-mcp23[](https://www.typescriptlang.org/)4[](https://modelcontextprotocol.io/)5[](https://www.npmjs.com/package/ntfy-me-mcp)6[](https://hub.docker.com/r/gitmotion/ntfy-me-mcp)7[](LICENSE)8[](https://github.com/gitmotion/ntfy-me-mcp)9<a href="https://www.buymeacoffee.com/gitmotion" target="_blank" rel="noopener noreferrer">10<img src="https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png" alt="Buy me a coffee" width="105px" />11</a>1213> A streamlined Model Context Protocol (MCP) server for sending notifications via ntfy service (public or selfhosted with token support) 📲1415## Overview1617ntfy-me-mcp provides AI assistants with the ability to send real-time notifications to your devices through the [ntfy](https://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.1819The 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.2021<img src="https://m2tg1pnwn0.ufs.sh/f/GMqNN8nd9I8lvhAeasbt6OQorL7fKJdgMSekE0Wanp5HXNIm" alt="autodetect-preview" width=50%>2223### Available via:2425| Name | Link / Badge |26| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |27| Glama.ai | <a href="https://glama.ai/mcp/servers/@gitmotion/ntfy-me-mcp"><img width="250" src="https://glama.ai/mcp/servers/@gitmotion/ntfy-me-mcp/badge" alt="ntfy-me-mcp MCP server" /></a> |28| Smithery.ai | [](https://smithery.ai/server/@gitmotion/ntfy-me-mcp) |29| MseeP.ai | <a href="https://mseep.ai/app/gitmotion-ntfy-me-mcp"><img width="150" src="https://mseep.net/pr/gitmotion-ntfy-me-mcp-badge.png" alt="ntfy-me-mc-mseepai" /></a> |30| Archestra.ai | [](https://archestra.ai/mcp-catalog/gitmotion__ntfy-me-mcp)</a> |3132## Table of Contents3334- [Features](#features)35 - [Coming soon...](#coming-soon)36- [Quickstart - MCP Server Configuration](#quickstart---mcp-server-configuration)37 - [NPM / NPX (Recommended Method)](#npm--npx-recommended-method)38 - [Minimal Configuration](#minimal-configuration-for-public-topics-on-ntfysh)39 - [Full Configuration](#full-configuration-for-private-servers-or-protected-topics)40 - [Option 1: Direct Token](#option-1-direct-token-in-configuration-less-secure)41 - [Option 2: VS Code Inputs](#option-2-using-vs-code-inputs-for-secure-token-handling-recommended)42 - [Docker](#docker)43 - [Using with MCP in Docker](#using-with-mcp-in-docker)44- [Installation](#installation)45 - [Option 1: Install Globally](#option-1-install-globally)46 - [Option 2: Run with npx](#option-2-run-with-npx)47 - [Option 3: Install Locally](#option-3-install-locally)48 - [Option 4: Build and Use Locally](#option-4-build-and-use-locally-with-node-command)49 - [Using locally built server with MCP](#using-locally-built-server-with-mcp)50 - [Option 5: MCP Marketplace Installations](#option-5-mcp-marketplace-installations)51- [Configuration](#configuration)52 - [Environment Variables](#environment-variables)53- [Usage](#usage)54 - [Authentication](#authentication)55 - [Setting Up the Notification Receiver](#setting-up-the-notification-receiver)56 - [Sending Notifications (ntfy_me tool)](#sending-notifications-ntfy_me-tool)57 - [Using Natural Language](#using-natural-language)58 - [Message Parameters](#message-parameters)59 - [Action Links](#action-links)60 - [Emoji Shortcodes](#emoji-shortcodes)61 - [Markdown Formatting](#markdown-formatting)62 - [Retrieving Messages (ntfy_me_fetch tool)](#retrieving-messages-ntfy_me_fetch-tool)63 - [Using Natural Language](#using-natural-language-1)64 - [Message Parameters](#message-parameters-1)65 - [Examples](#examples)66 - [Development](#development)67 - [Building from Source](#building-from-source)68- [License](#license)69- [Contributing](#contributing)7071## Features7273- 🚀 **Quick Setup**: Run with npx or docker!74- 🔔 **Real-time Notifications**: Get updates on your phone/desktop when tasks complete75- 🎨 **Rich Notifications**: Support for topic, title, priorities, emoji tags, and detailed messages76- 🔍 **Notification Fetching**: Fetch and filter cached messages from your ntfy topics77- 🎯 **Smart Action Links**: Automatically detects URLs in messages and creates view actions78- 📄 **Intelligent Markdown**: Auto-detects and enables markdown formatting when present79- 🔒 **Secure**: Optional authentication with access tokens80- 🔑 **Input Masking**: Securely store your ntfy token in your vs config!81- 🌐 **Self-hosted Support**: Works with both ntfy.sh and self-hosted ntfy instances8283### (Coming soon...)8485- 📨 **Email**: Send notifications to email (requires ntfy email server configuration)86- 🔗 **Click urls**: Ability to customize click urls87- 🖼️ **Image urls**: Intelligent image url detection to automatically include image urls in messages and notifications88- 🏁 and more!8990## Quickstart - MCP Server Configuration9192### NPM / NPX (Recommended Method)9394- Requires npm / npx installed on your system.95- This method is recommended for most users as it provides a simple & lightweight method to set up the server.9697For the easiest setup with MCP-compatible assistants, add this to your MCP configuration:9899#### Minimal configuration (for public topics on ntfy.sh)100101```json102{103 "ntfy-me-mcp": {104 "command": "npx",105 "args": ["ntfy-me-mcp"],106 "env": {107 "NTFY_TOPIC": "your-topic-name"108 }109 }110}111```112113#### Full configuration (for private servers or protected topics)114115#### Option 1: Direct token in configuration116117```json118{119 "ntfy-me-mcp": {120 "command": "npx",121 "args": ["ntfy-me-mcp"],122 "env": {123 "NTFY_TOPIC": "your-topic-name",124 "NTFY_URL": "https://your-ntfy-server.com",125 "NTFY_TOKEN": "your-auth-token" // Use if using a protected topic/server126 }127 }128}129```130131#### Option 2: Using VS Code inputs for secure token handling (recommended)132133Add this to your VS Code settings.json file:134135```json136"mcp": {137 "inputs": [138 { // Add this to your inputs array139 "type": "promptString",140 "id": "ntfy_token",141 "description": "Ntfy Token",142 "password": true143 }144 ],145 "servers": {146 // Other servers...147 "ntfy-me-mcp": {148 "command": "npx",149 "args": ["ntfy-me-mcp"],150 "env": {151 "NTFY_TOPIC": "your-topic-name",152 "NTFY_URL": "https://your-ntfy-server.com",153 "NTFY_TOKEN": "${input:ntfy_token}", // Use the input id variable for the token154 "PROTECTED_TOPIC": "true" // Prompts for token and masks it in your config155 }156 }157 }158}159```160161With this setup, VS Code will prompt you for the token when starting the server and the token will be masked when entered.162163## Docker164165### Using with MCP in Docker166167- Requires Docker installed on your system.168- This method is useful for running the server in a containerized environment.169- You can use the official Docker images available on Docker Hub or GitHub Container Registry.170171Docker Images:172173- `gitmotion/ntfy-me-mcp:latest` (Docker Hub)174- `ghcr.io/gitmotion/ntfy-me-mcp:latest` (GitHub Container Registry)175176In your MCP configuration (e.g., VS Code settings.json):177178```json179"mcp": {180 "servers": {181 "ntfy-mcp": {182 "command": "docker",183 "args": [184 "run",185 "-i",186 "--rm",187 "-e",188 "NTFY_TOPIC",189 "-e",190 "NTFY_URL",191 "-e",192 "NTFY_TOKEN",193 "-e",194 "PROTECTED_TOPIC",195 "gitmotion/ntfy-me-mcp", // OR use ghcr.io/gitmotion/ntfy-me-mcp:latest196 ],197 "env": {198 "NTFY_TOPIC": "your-topic-name",199 "NTFY_URL": "https://your-ntfy-server.com",200 "NTFY_TOKEN": "${input:ntfy_token}",201 "PROTECTED_TOPIC": "true"202 }203 }204 }205}206```207208## Installation209210If you need to install and run the server directly (alternative to the MCP configuration above):211212### Option 1: Install globally213214```bash215npm install -g ntfy-me-mcp216```217218### Option 2: Run with npx219220```bash221npx ntfy-me-mcp222```223224### Option 3: Install locally225226```bash227# Clone the repository228git clone https://github.com/gitmotion/ntfy-me-mcp.git229cd ntfy-me-mcp230231# Install dependencies232npm install233234# Copy the example environment file and configure it235cp .env.example .env236# Edit .env with your preferred editor and update the variables237# nano .env # or use your preferred editor238239# Build the project240npm run build241242# Start the server243npm start244```245246### Option 4: Build and use locally with node command247248If you're developing or customizing the server, you might want to run it directly with node:249250```bash251# Clone the repository252git clone https://github.com/gitmotion/ntfy-me-mcp.git253cd ntfy-me-mcp254255# Install dependencies256npm install257258# Copy the example environment file and configure it259cp .env.example .env260# Edit the .env file to set your NTFY_TOPIC and other optional settings261# nano .env # or use your preferred editor262263# Build the project264npm run build265266# Run using node directly267npm start268```269270#### Using locally built server with MCP271272When configuring your MCP to use a locally built version, specify the node command and path to the built index.js file:273274```json275{276 "ntfy-me": {277 "command": "node",278 "args": ["/path/to/ntfy-mcp/build/index.js"],279 "env": {280 "NTFY_TOPIC": "your-topic-name"281 //"NTFY_URL": "https://your-ntfy-server.com", // Use if using a self-hosted server282 //"NTFY_TOKEN": "your-auth-token" // Use if using a protected topic/server283 }284 }285}286```287288Remember to use the absolute path to your build/index.js file in the args array.289290### Option 5: MCP Marketplace installations291292#### Installing via Smithery293294To install ntfy-me-mcp for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@gitmotion/ntfy-me-mcp):295296```bash297npx -y @smithery/cli install @gitmotion/ntfy-me-mcp --client claude298```299300## Configuration301302### Environment Variables303304Create a `.env` file in your project directory by copying the provided example:305306```bash307# Copy the example file308cp .env.example .env309310# Edit the file with your preferred editor311nano .env # or vim, code, etc.312```313314Your `.env` file should contain these variables:315316```317# Required318NTFY_TOPIC=your-topic-name319320# Optional - Configure these if using a private/protected ntfy server321# NTFY_URL=https://ntfy.sh # Default is ntfy.sh, change to your self-hosted ntfy server URL if needed322 # Include port if needed, e.g., https://your-ntfy-server.com:8443323# NTFY_TOKEN=your-access-token # Required for authentication with protected topics/servers324# PROTECTED_TOPIC=false # Set to "true" if your topic requires authentication (helps prevent auth errors)325```326327> **Note**: The `PROTECTED_TOPIC` flag helps the application determine whether authentication is required for your topic. When set to "true" and no token is provided, you'll be prompted to enter one. This prevents authentication failures with protected topics.328329## Usage330331### Authentication332333This server supports both authenticated and unauthenticated ntfy endpoints:334335- **Public Topics**: When using public topics on ntfy.sh or other public servers, no authentication is required.336- **Protected Topics**: For protected topics or private servers, you need to provide an access token.337338If authentication is required but not provided, you'll receive a clear error message explaining how to add your token.339340### Setting Up the Notification Receiver3413421. Install the [ntfy app](https://ntfy.sh/app) on your device3432. Subscribe to your chosen topic (the same as your `NTFY_TOPIC` setting)344345### Sending Notifications (ntfy_me tool)346347This section covers all functionality related to sending notifications using the ntfy_me tool.348349#### Using Natural Language350351When working with your AI assistant, you can use natural phrases like:352353```354"Send me a notification when the build is complete"355"Notify me when the task is done"356"Alert me after generating the code"357"Message me when the process finishes"358"Send an alert with high priority"359```360361#### Message Parameters362363The tool accepts these parameters:364365| Parameter | Description | Required |366| ----------- | ------------------------------------------------------ | -------- |367| taskTitle | The notification title | Yes |368| taskSummary | The notification body | Yes |369| priority | Message priority: min, low, default, high, max | No |370| tags | Array of notification tags (supports emoji shortcodes) | No |371| markdown | Boolean to enable markdown formatting (true/false) | No |372| actions | Array of view action objects for clickable links | No |373374Example:375376```javascript377{378 taskTitle: "Code Generation Complete",379 taskSummary: "Your React component has been created successfully with proper TypeScript typing.",380 priority: "high",381 tags: ["check", "code", "react"]382}383```384385This will send a high-priority notification with a checkmark emoji.386387#### Action Links388389You can add clickable action buttons to your notifications using the `actions` parameter, or let the server automatically detect URLs in your message.390391##### Automatic URL Detection392393When URLs are present in the message body, the server automatically creates up to 3 view actions (ntfy's maximum limit) from the first detected URLs. This makes it easy to include clickable links without manually specifying the actions array.394395For example, this message:396397```javascript398{399 taskTitle: "Build Complete",400 taskSummary: "Your PR has been merged! View the changes at https://github.com/org/repo/pull/123 or check the deployment at https://staging.app.com"401}402```403404Will automatically generate view actions for both URLs, making them easily clickable in the notification.405406##### Manual Action Configuration407408For more control, you can manually specify actions:409410| Property | Description | Required |411| -------- | ------------------------------------------------- | -------- |412| action | Must be "view" | Yes |413| label | Button text to display | Yes |414| url | URL to open when clicked | Yes |415| clear | Whether to clear notification on click (optional) | No |416417Example with action links:418419```javascript420{421 taskTitle: "Pull Request Review",422 taskSummary: "Your code has been reviewed and is ready for final checks",423 priority: "high",424 tags: ["check", "code"],425 actions: [426 {427 action: "view",428 label: "View PR",429 url: "https://github.com/org/repo/pull/123"430 },431 {432 action: "view",433 label: "View Changes",434 url: "https://github.com/org/repo/pull/123/files",435 clear: true436 }437 ]438}439```440441#### Emoji Shortcodes442443You can use emoji shortcodes in your tags for visual indicators:444445- `warning` → ⚠️446- `check` → ✅447- `rocket` → 🚀448- `tada` → 🎉449450See the [full list of supported emoji shortcodes](https://docs.ntfy.sh/emojis/).451452#### Markdown Formatting453454Your notifications support rich markdown formatting with intelligent detection! When you include markdown syntax in your `taskSummary`, the server automatically detects it and enables markdown parsing - no need to set `markdown: true` explicitly.455456##### Automatic Detection457458The server checks for common markdown patterns like:459460- Headers (#, ##, etc.)461- Lists (-, \*, numbers)462- Code blocks (```)463- Links ([text](url))464- Bold/italic (_text_, **text**)465466When these patterns are detected, markdown parsing is automatically enabled for the message.467468##### Manual Override469470While automatic detection works in most cases, you can still explicitly control markdown parsing:471472```javascript473{474 taskTitle: "Task Complete",475 taskSummary: "Regular plain text message",476 markdown: false // Force disable markdown parsing477}478```479480### Retrieving Messages (ntfy_me_fetch tool)481482This section covers all functionality related to fetching and filtering messages using the ntfy_me_fetch tool.483484#### Using Natural Language485486AI assistants understand various ways to request message fetching:487488```489"Show me my recent notifications"490"Get messages from the last hour"491"Find notifications with title 'Build Complete'"492"Search for messages with the test_tube tag"493"Show notifications from the updates topic from the last 24hr"494"Check my latest alerts"495```496497#### Message Parameters498499The tool accepts these parameters:500501| Parameter | Description | Required |502| ------------ | -------------------------------------------------------------------------------------- | -------- |503| ntfyTopic | Topic to fetch messages from (defaults to NTFY_TOPIC env var) | No |504| since | How far back to retrieve messages ('10m', '1h', '1d', timestamp, message ID, or 'all') | No |505| messageId | Find a specific message by its ID | No |506| messageText | Find messages containing exact text content | No |507| messageTitle | Find messages with exact title/subject | No |508| priorities | Find messages with specific priority levels | No |509| tags | Find messages with specific tags | No |510511#### Examples5125131. **Fetch Recent Messages**514515```javascript516{517 since: "30m"; // Get messages from last 30 minutes518}519```5205212. **Filter by Title and Priority**522523```javascript524{525 messageTitle: "Build Complete",526 priorities: "high",527 since: "1d"528}529```5305313. **Search Different Topic with Tags**532533```javascript534{535 ntfyTopic: "updates",536 tags: ["error", "warning"],537 since: "all"538}539```5405414. **Find Specific Message**542543```javascript544{545 messageId: "xxxxXXXXxxxx";546}547```548549Messages are returned with full details including:550551- Message ID and timestamp552- Topic and title553- Content and priority554- Tags and attachments555- Action links and expiration556557> **Note**: Message history availability depends on your ntfy server's cache settings. The public ntfy.sh server typically caches messages for 12 hours.558559## Development & Contributions560561### Building from Source562563```bash564git clone https://github.com/gitmotion/ntfy-me-mcp.git565cd ntfy-me-mcp566npm install567npm run build568```569570## License571572This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.573574## Contributing575576Contributions are welcome! Please follow these guidelines:577578- Point your pull requests to the `dev` or `testing` branches (not `main`).579- For all logging, use the `Logger` class abstraction:580 - Replace any `console.log`, `console.warn`, or `console.error` with `logger.info`, `logger.warn`, or `logger.error`.581- Ensure your code is clean, well-documented, and passes all tests.582- Clearly describe your changes in the PR description.583- For local testing:584 - Build the project with `npm run build`.585 - Run the server locally using `npm start` or `node build/index.js`.586 - Test your changes before submitting a PR.587588Thank you for helping improve ntfy-me-mcp!589590---591592Made with ❤️ by [gitmotion](https://github.com/gitmotion)593
Full transparency — inspect the skill content before installing.