<img src="https://m2tg1pnwn0.ufs.sh/f/GMqNN8nd9I8l9tUbmif1CnFX8Baqr7mHeicYu0AULDyNVWJE" width=30 /> ntfy-me-mcp

<a href="https://www.buymeacoffee.com/gitmotion" target="_blank" rel="noopener noreferrer"> <img src="https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png" alt="Buy me a coffee" width="105px" /> </a>

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 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.

<img src="https://m2tg1pnwn0.ufs.sh/f/GMqNN8nd9I8lvhAeasbt6OQorL7fKJdgMSekE0Wanp5HXNIm" alt="autodetect-preview" width=50%>

Available via:

Table of Contents

• Features
  • Coming soon...
• Quickstart - MCP Server Configuration
  • NPM / NPX (Recommended Method)
    • Minimal Configuration
    • Full Configuration
      • Option 1: Direct Token
      • Option 2: VS Code Inputs
  • Docker
    • Using with MCP in Docker
• Installation
  • Option 1: Install Globally
  • Option 2: Run with npx
  • Option 3: Install Locally
  • Option 4: Build and Use Locally
    • Using locally built server with MCP
  • Option 5: MCP Marketplace Installations
• Configuration
  • Environment Variables
• Usage
  • Authentication
  • Setting Up the Notification Receiver
  • Sending Notifications (ntfy_me tool)
    • Using Natural Language
    • Message Parameters
    • Action Links
    • Emoji Shortcodes
    • Markdown Formatting
  • Retrieving Messages (ntfy_me_fetch tool)
    • Using Natural Language
    • Message Parameters
    • Examples
  • Development
    • Building from Source
• License
• Contributing

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!

Quickstart - MCP Server Configuration

NPM / NPX (Recommended Method)

• Requires npm / npx installed on your system.
• This method is recommended for most users as it provides a simple & lightweight method to set up the server.

For the easiest setup with MCP-compatible assistants, add this to your MCP configuration:

Minimal configuration (for public topics on ntfy.sh)

{
  "ntfy-me-mcp": {
    "command": "npx",
    "args": ["ntfy-me-mcp"],
    "env": {
      "NTFY_TOPIC": "your-topic-name"
    }
  }
}

Full configuration (for private servers or protected topics)

Option 1: Direct token in configuration

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

Option 2: Using VS Code inputs for secure token handling (recommended)

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

Using with MCP in Docker

• Requires Docker installed on your system.
• This method is useful for running the server in a containerized environment.
• You can use the official Docker images available on Docker Hub or GitHub Container Registry.

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

Installation

If you need to install and run the server directly (alternative to the MCP configuration above):

Option 1: Install globally

npm install -g ntfy-me-mcp

Option 2: Run with npx

npx ntfy-me-mcp

Option 3: Install locally

# 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

Option 4: Build and use locally with node command

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 

---