Ntfy MCP Server

Table of Contents

• [Overview](#overview)

• [Features](#features)

• [Quick Start](#quick-start)

• [Installation](#installation)

• [Configuration](#configuration)

• [Project Structure](#project-structure)

• [Tools](#tools)

• [Resources](#resources)

• [Use Cases](#use-cases)

• [Available Scripts](#available-scripts)

• [Contributing](#contributing)

• [License](#license)

Overview

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:** ```bash # 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](#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:** ```bash 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:** ```bash 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:** ```bash git clone https://github.com/cyanheads/ntfy-mcp-server.git cd ntfy-mcp-server ```

2. **Install dependencies:** ```bash npm install ```

3. **Build the project:** ```bash npm run build ```

Configuration

Environment Variables

MCP Client Settings

For Cline VSCode Extension

For Claude Desktop App

Ntfy Setup

1. **Install the ntfy app** on your devices from [ntfy.sh](https://ntfy.sh/app) or the app stores

2. **Subscribe to your topic** in the app

3. **Use the same topic** in your MCP server configuration

Project Structure

Tools

`send_ntfy`

Key Arguments:

Example Usage:

Example Response:

Resources

Direct Resources

`ntfy://default`

• **Description:** Returns the default ntfy topic configured in the server's environment variables (`NTFY_DEFAULT_TOPIC`).

• **Usage:** Useful for clients to discover the primary topic without needing prior configuration.

• **Example:** An LLM agent can access this resource to automatically use the default topic when sending notifications.

• **Example Response:** ```json { "defaultTopic": "ATLAS", "timestamp": "2025-03-27T08:30:25.619Z", "requestUri": "ntfy://default", "requestId": "0da963d0-30e0-4dbc-bb77-4bf2dee14484" } ```

Resource Templates

`ntfy://{topic}`

• **Description:** Returns information about a specific ntfy topic.

• **Parameters:** `topic` - The name of the ntfy topic.

• **Usage:** For querying information about topics other than the default.

• **Example Response:** ```json { "topic": "ATLAS", "timestamp": "2025-03-27T08:30:30.038Z", "requestUri": "ntfy://ATLAS", "requestId": "31baf1df-278f-4fdb-860d-019f156a72b0" } ```

Use Cases

1. **Long-running Task Notifications** - Get notified when tasks like database backups, code generation, or data processing complete.

2. **Scheduled Reminders** - Set delayed notifications for future events or reminders.

3. **Alert Systems** - Set up critical alerts for monitoring systems or important events.

4. **Mobile Notifications from LLMs** - Allow LLMs to send notifications directly to your phone.

5. **Multi-step Process Updates** - Receive updates as different stages of a complex process complete.

Usage Examples

Basic Notification

Rich Notification with Actions

Available Scripts

• `npm run build`: Compiles the TypeScript source code to JavaScript in the `dist/` directory.

• `npm run clean`: Removes the `dist/` directory and cleans the contents of the `logs/` directory.

• `npm run rebuild`: Runs `clean` and then `build`.

• `npm run tree`: Generates a directory tree representation in `docs/tree.md`.

• `npm start`: Runs the compiled server from the `dist/` directory using Node.js.

• `npm run watch`: Tails the combined log file (`logs/combined.log`) for real-time monitoring.

Contributing

1. Fork the repository.

2. Create a feature branch (`git checkout -b feature/your-feature`).

3. Commit your changes (`git commit -m 'Add some feature'`).

4. Push to the branch (`git push origin feature/your-feature`).

5. Create a new Pull Request.

Development Best Practices

• Follow TypeScript best practices and maintain strong typing

• Write tests for new functionality

• Keep dependencies up to date

• Follow the existing code style and patterns

License

Acknowledgements

• [ntfy.sh](https://ntfy.sh/) for providing the notification service

• [Model Context Protocol](https://modelcontextprotocol.io/) for enabling LLM-to-tool connections

• All contributors and users of this project