ntfy-mcp-server

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
• Features
• Quick Start
• Installation
• Configuration
• Project Structure
• Tools
• Resources
• Use Cases
• Available Scripts
• Contributing
• License

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.

┌───────────┐      ┌───────────┐      ┌───────────┐      ┌─────────┐
│ LLM Agent │ ────▶│ Ntfy MCP  │ ────▶│ Ntfy      │ ────▶│ Your    │
│ (Claude)  │      │ Server    │      │ Service   │      │ Devices │
└───────────┘      └───────────┘      └───────────┘      └─────────┘

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 and winston-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

1. Prerequisites:

   • Node.js (v16+)
   • npm or yarn
   • An MCP-compatible client (Claude Desktop, Cline, etc.)

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

3. Add to MCP Client Settings: Add the server to your MCP client settings file (see Configuration)

4. Use the tool: Once connected, you can use the send_ntfy tool to send notifications.

Installation

Option 1: NPM Package (Recommended)

1. Install the package globally:

   npm install -g ntfy-mcp-server
   

   This will install the server globally, making it available as a command-line tool.

2. Or install locally in your project:

   npm install ntfy-mcp-server
   

   When installed locally, you can run it via npx or from node.

Option 2: From Source

1. Clone the repository:

   git clone https://github.com/cyanheads/ntfy-mcp-server.git
   cd ntfy-mcp-server
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

Environment Variables

Create a .env file in the project root based on .env.example:

# Ntfy Configuration
NTFY_BASE_URL=https://ntfy.sh  # Optional: Base URL of your ntfy instance
NTFY_DEFAULT_TOPIC=your_default_topic # Optional: Default topic if none specified in requests

# Application Configuration
LOG_LEVEL=info # Optional: Logging level (debug, info, warn, error)
NODE_ENV=development # Optional: Environment (development, production)

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:

{
  "mcpServers": {
    "ntfy": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "ntfy": {
      "command": "node",
      "args": ["/path/to/ntfy-mcp-server/dist/index.js"],
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

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:

{
  "mcpServers": {
    "ntfy": {
      "command": "ntfy-mcp-server",
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "ntfy": {
      "command": "node",
      "args": ["/path/to/ntfy-mcp-server/dist/index.js"],
      "env": {
        "NTFY_BASE_URL": "https://ntfy.sh",
        "NTFY_DEFAULT_TOPIC": "your_default_topic",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production"
      }
    }
  }
}

For source installation, replace /path/to/ntfy-mcp-server/dist/index.js with the actual absolute path to the built server file. Adjust env variables as needed for your setup.

Ntfy Setup

1. Install the ntfy app on your devices from ntfy.sh or the app stores
2. Subscribe to your topic in the app
3. Use the same topic in your MCP server configuration

Project Structure

.
├── .env.example            # Example environment variables
├── .gitignore              # Git ignore patterns
├── LICENSE                 # Project license (Apache-2.0)
├── package.json            # Project metadata and dependencies
├── tsconfig.json           # TypeScript compiler configuration
├── docs/
│   └── tree.md             # Auto-generated directory structure
├── logs/                   # Runtime logs (created automatically)
├── scripts/                # Utility scripts
│   ├── clean.ts            # Cleans build artifacts and logs
│   └── tree.ts             # Generates the docs/tree.md file
└── src/                    # Source code
    ├── index.ts            # Main server entry point
    ├── config/             # Configuration loading
    ├── mcp-server/         # MCP server logic, tools, and resources
    │   ├── resources/      # MCP resource implementations
    │   ├── tools/          # MCP tool implementations
    │   └── utils/          # MCP-specific utilities
    ├── services/           # External service integrations (ntfy)
    ├── types-global/       # Global type definitions
    └── utils/              # General utility functions

Tools

send_ntfy

Sends a notification message via the ntfy service.

Key Arguments:

Parameter	Type	Required	Description
topic	string	Yes	The ntfy topic to publish to.
message	string	Yes	The main content of the notification (max 4096 bytes).
title	string	No	Notification title (max 250 bytes).
tags	string[]	No	Emojis or keywords for categorization (e.g., ["warning", "robot"]). Max 5.
priority	integer	No	Message priority: 1=min, 2=low, 3=default, 4=high, 5=max.
click	string	No	URL to open when the notification is clicked.
actions	array	No	Action buttons (view, http, broadcast). Max 3.
attachment	object	No	URL and name of an attachment.
email	string	No	Email address to forward the notification to.
delay	string	No	Delay delivery (e.g., 30m, 1h, tomorrow).
cache	string	No

---

README truncated. View full README on GitHub.