An ntfy MCP server for sending/fetching ntfy notifications to any/self-hosted ntfy.sh server from AI Agents 📤 (supports secure token auth & more - use with npx or docker!)
A streamlined Model Context Protocol (MCP) server for sending notifications via ntfy service (public or selfhosted with token support) 📲
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 and smart markdown formatting detection, making it easier for AI assistants to create rich, interactive notifications without extra configuration.
| Name | Link / Badge |
|---|---|
| Glama.ai | |
| Smithery.ai | |
| MseeP.ai |  |
For the easiest setup with MCP-compatible assistants, add this to your MCP configuration:
{
"ntfy-me-mcp": {
"command": "npx",
"args": ["ntfy-me-mcp"],
"env": {
"NTFY_TOPIC": "your-topic-name"
}
}
}
{
"ntfy-me-mcp": {
"command": "npx",
"args": ["ntfy-me-mcp"],
"env": {
"NTFY_TOPIC": "your-topic-name",
"NTFY_URL": "https://your-ntfy-server.com",
"NTFY_TOKEN": "your-auth-token" // Use if using a protected topic/server
}
}
}
Add this to your VS Code settings.json file:
"mcp": {
"inputs": [
{ // Add this to your inputs array
"type": "promptString",
"id": "ntfy_token",
"description": "Ntfy Token",
"password": true
}
],
"servers": {
// Other servers...
"ntfy-me-mcp": {
"command": "npx",
"args": ["ntfy-me-mcp"],
"env": {
"NTFY_TOPIC": "your-topic-name",
"NTFY_URL": "https://your-ntfy-server.com",
"NTFY_TOKEN": "${input:ntfy_token}", // Use the input id variable for the token
"PROTECTED_TOPIC": "true" // Prompts for token and masks it in your config
}
}
}
}
With this setup, VS Code will prompt you for the token when starting the server and the token will be masked when entered.
Docker Images:
gitmotion/ntfy-me-mcp:latest (Docker Hub)ghcr.io/gitmotion/ntfy-me-mcp:latest (GitHub Container Registry)In your MCP configuration (e.g., VS Code settings.json):
"mcp": {
"servers": {
"ntfy-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"NTFY_TOPIC",
"-e",
"NTFY_URL",
"-e",
"NTFY_TOKEN",
"-e",
"PROTECTED_TOPIC",
"gitmotion/ntfy-me-mcp", // OR use ghcr.io/gitmotion/ntfy-me-mcp:latest
],
"env": {
"NTFY_TOPIC": "your-topic-name",
"NTFY_URL": "https://your-ntfy-server.com",
"NTFY_TOKEN": "${input:ntfy_token}",
"PROTECTED_TOPIC": "true"
}
}
}
}
If you need to install and run the server directly (alternative to the MCP configuration above):
npm install -g ntfy-me-mcp
npx ntfy-me-mcp
## Clone the repository
git clone https://github.com/gitmotion/ntfy-me-mcp.git
cd ntfy-me-mcp
## Install dependencies
npm install
## Copy the example environment file and configure it
cp .env.example .env
## Edit .env with your preferred editor and update the variables
## nano .env # or use your preferred editor
## Build the project
npm run build
## Start the server
npm start
If you’re developing or customizing the server, you might want to run it directly with node:
## Clone the repository
git clone https://github.com/gitmotion/ntfy-me-mcp.git
cd ntfy-me-mcp
## Install dependencies
npm install
## Copy the example environment file and configure it
cp .env.example .env
## Edit the .env file to set your NTFY_TOPIC and other optional settings
## nano .env # or use your preferred editor
## Build the project
npm run build
## Run using node directly
npm start
When configuring your MCP to use a locally built version, specify the node command and path to the built index.js file:
{
"ntfy-me": {
"command": "node",
"args": ["/path/to/ntfy-mcp/build/index.js"],
"env": {
"NTFY_TOPIC": "your-topic-name",
//"NTFY_URL": "https://your-ntfy-server.com", // Use if using a self-hosted server
//"NTFY_TOKEN": "your-auth-token" // Use if using a protected topic/server
}
}
}
Remember to use the absolute path to your build/index.js file in the args array.
To install ntfy-me-mcp for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @gitmotion/ntfy-me-mcp --client claude
Create a .env file in your project directory by copying the provided example:
## Copy the example file
cp .env.example .env
## Edit the file with your preferred editor
nano .env # or vim, code, etc.
Your .env file should contain these variables:
## Required
NTFY_TOPIC=your-topic-name
## Optional - Configure these if using a private/protected ntfy server
## NTFY_URL=https://ntfy.sh # Default is ntfy.sh, change to your self-hosted ntfy server URL if needed
# Include port if needed, e.g., https://your-ntfy-server.com:8443
## NTFY_TOKEN=your-access-token # Required for authentication with protected topics/servers
## PROTECTED_TOPIC=false # Set to "true" if your topic requires authentication (helps prevent auth errors)
Note: The
PROTECTED_TOPICflag 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.
This server supports both authenticated and unauthenticated ntfy endpoints:
If authentication is required but not provided, you’ll receive a clear error message explaining how to add your token.
NTFY_TOPIC setting)This section covers all functionality related to sending notifications using the ntfy_me tool.
When working with your AI assistant, you can use natural phrases like:
"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"
The tool accepts these parameters:
| Parameter | Description | Required |
|---|---|---|
| taskTitle | The notification title | Yes |
| taskSummary | The notification body | Yes |
| priority | Message priority: min, low, default, high, max | No |
| tags | Array of notification tags (supports emoji shortcodes) | No |
| markdown | Boolean to enable markdown formatting (true/false) | No |
| actions | Array of view action objects for clickable links | No |
Example:
{
taskTitle: "Code Generation Complete",
taskSummary: "Your React component has been created successfully with proper TypeScript typing.",
priority: "high",
tags: ["check", "code", "react"]
}
This will send a high-priority notification with a checkmark emoji.
You can add clickable action buttons to your notifications using the actions parameter, or let the server automatically detect URLs in your message.
When URLs are present in your 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.
For example, this message:
{
taskTitle: "Build Complete",
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"
}
Will automatically generate view actions for both URLs, making them easily clickable in the notification.
For more control, you can manually specify actions:
| Property | Description | Required |
|---|---|---|
| action | Must be “view” | Yes |
| label | Button text to display | Yes |
| url | URL to open when clicked | Yes |
| clear | Whether to clear notification on click (optional) | No |
Example with action links:
{
taskTitle: "Pull Request Review",
taskSummary: "Your code has been reviewed and is ready for final checks",
priority: "high",
tags: ["check", "code"],
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
}
]
}
You can use emoji shortcodes in your tags for visual indicators:
warning → ⚠️check → ✅rocket → 🚀tada → 🎉See the full list of supported emoji shortcodes.
Your 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.
The server checks for common markdown patterns like:
When these patterns are detected, markdown parsing is automatically enabled for the message.
While automatic detection works in most cases, you can still explicitly control markdown parsing:
{
taskTitle: "Task Complete",
taskSummary: "Regular plain text message",
markdown: false // Force disable markdown parsing
}
This section covers all functionality related to fetching and filtering messages using the ntfy_me_fetch tool.
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"
The tool accepts these parameters:
| Parameter | Description | Required |
|---|---|---|
| ntfyTopic | Topic to fetch messages from (defaults to NTFY_TOPIC env var) | No |
| since | How far back to retrieve messages (‘10m’, ‘1h’, ‘1d’, timestamp, message ID, or ‘all’) | No |
| messageId | Find a specific message by its ID | No |
| messageText | Find messages containing exact text content | No |
| messageTitle | Find messages with exact title/subject | No |
| priorities | Find messages with specific priority levels | No |
| tags | Find messages with specific tags | No |
{
since: "30m" // Get messages from last 30 minutes
}
{
messageTitle: "Build Complete",
priorities: "high",
since: "1d"
}
{
ntfyTopic: "updates",
tags: ["error", "warning"],
since: "all"
}
{
messageId: "xxxxXXXXxxxx"
}
Messages are returned with full details including:
Note: Message history availability depends on your ntfy server’s cache settings. The public ntfy.sh server typically caches messages for 12 hours.
git clone https://github.com/gitmotion/ntfy-me-mcp.git
cd ntfy-me-mcp
npm install
npm run build
This project is licensed under the GNU General Public License v3.0 - see the LICENSE{:target=“_blank”} file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
Made with ❤️ by gitmotion