Ntfy Mcp

What is Ntfy Mcp about?

Ntfy Mcp notifies you via ntfy whenever a task completed by an AI assistant reaches the end of its execution. It acts as a lightweight MCP server that bridges the Model Context Protocol with the ntfy notification service.

How to use Ntfy Mcp?

1. Clone the repository

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

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Start the server (manual)

   npm start
   

   or run it through an MCP client configuration:

   {
     "ntfy-mcp": {
       "command": "node",
       "args": ["/path/to/ntfy-mcp/build/index.js"],
       "env": {"NTFY_TOPIC": "<your topic name>"},
       "autoApprove": ["notify_user"]
     }
   }
   

5. Configure the notification topic by setting the NTFY_TOPIC environment variable to the ntfy topic you subscribe to.
6. Subscribe to the same topic in the ntfy app (mobile or web) and you’ll receive a push when the task finishes.

Key Features

• Sends ntfy push notifications on task completion.
• Simple CLI start (npm start) or integrated MCP client configuration.
• Topic configurable via NTFY_TOPIC environment variable.
• Auto‑approves the notify_user action for seamless alerts.
• Built with TypeScript, leveraging @modelcontextprotocol/sdk.

Use Cases

• Developers monitoring long‑running AI code‑generation or testing jobs.
• Teams needing a non‑intrusive alert when background AI workflows finish.
• Personal productivity setups where you want a coffee‑break reminder after an AI‑driven task.

FAQ

Q: How do I set the ntfy topic? A: Export NTFY_TOPIC in your environment or add it to the MCP client config.

Q: Do I need to run the build step each time? A: After code changes, yes. For regular use you can start the compiled version directly or use npx as shown below.

Q: Can I run the server without building? A: Yes, if you have ts-node installed you can execute the source, but the recommended approach is the built JavaScript.

Q: What are the required dependencies? A: Node.js (>=14), npm, and the packages listed in package.json (@modelcontextprotocol/sdk, node-fetch, dotenv, zod).

Q: What license does the project use? A: Apache License 2.0.

ntfy-mcp: Your Friendly Task Completion Notifier

Welcome to ntfy-mcp, the MCP server that keeps you caffeinated and informed! 🚀☕️

This handy little server integrates with the Model Context Protocol to send you delightful ntfy notifications whenever your AI assistant completes a task. Because let's face it - you deserve that tea break while your code writes itself.

Getting Started: The Quick Brew Guide

Step 1: Clone & Navigate

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

Step 2: Install

npm install

Step 3: Build

npm run build

Step 4: Connect

Choose your adventure:

Manual Start:

npm start

Cline Configuration:

"ntfy-mcp": {
  "command": "node",
  "args": [
    "/path/to/ntfy-mcp/build/index.js"
  ],
  "env": {
    "NTFY_TOPIC": "<your topic name>"
  },
  "autoApprove": [
    "notify_user" // Highly recommended for maximum chill
  ]
}

Step 5: Get Notified in Style

1. Download the ntfy app on your phone
2. Subscribe to your chosen topic
3. Kick back and relax

Step 6: The Magic Command

Write a prompt like this, otherwise the function won't call (tried use Custom Instructions in cline, but they are in the ring 3, so model just forget about it)

Write me a hello world in python, notify me when the task is done

Step 7: Enjoy Your Beverage of Choice

☕️🍵 Your notification will arrive when the task is complete. No peeking!

How It Works (The Technical Tea)

This MCP server integrates seamlessly with the Model Context Protocol, acting as your personal notification butler. When tasks are completed, it sends notifications via ntfy, keeping you informed without interrupting your flow.

Dependencies: The Secret Sauce

• @modelcontextprotocol/sdk
• node-fetch
• dotenv
• zod

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright 2025 Casey Hand @cyanheads

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

---

Now go forth and code with confidence, knowing your notifications are in good hands! 🎉