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!

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

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

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

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

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

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

{
  "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": ["*"]
    }
  }
}

{
  "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):

# 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

npx -y @smithery/cli install @gitmotion/ntfy-me-mcp --client claude

Setting Up the Notification Receiver

Configuration

Environment Variables

Create a .env file by copying the example: cp .env.example .env — see .env.example for reference.

Authentication

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

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

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

{
  title: "Task Complete",
  message: "Regular plain text message",
  markdown: false  // Force disable
}

{
  title: "Build Complete",
  message: "View at https://github.com/org/repo/pull/123"
}

{
  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

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

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