Ntfy MCP Server for Phone Notifications

Overview

The Ntfy MCP Server is a lightweight HTTP gateway that listens for Model Context Protocol (MCP) messages and forwards them as push notifications to your phone using ntfy (https://ntfy.sh). It lets tools, agents, or model components emit short alerts in a standardized JSON format and have those messages delivered immediately to an ntfy topic so you can stay informed while mobile.

This server is useful when you want a simple, reliable bridge between AI systems or automated services and a phone-based notification channel. Rather than building custom notification logic into each component, you expose MCP-compatible message hooks and let the Ntfy MCP Server translate and relay alerts to any ntfy-compatible client.

Features

• Receives MCP-style JSON messages over HTTP
• Forwards messages to ntfy topics (self-hosted or ntfy.sh)
• Configurable title, priority/severity, and body mapping
• Optional HTTP authentication for ntfy endpoints
• Runs as a standalone binary or in Docker
• Simple environment-driven configuration suitable for containers

Installation / Configuration

Prerequisites:

• ntfy server or an ntfy.sh account (https://ntfy.sh)
• Docker (recommended) or a host that can run the provided binary

Quick start with Docker:

# Run with default ntfy.sh and topic "alerts"
docker run -d --name ntfy-mcp \
  -e NTFY_TOPIC=alerts \
  -e PORT=8080 \
  -p 8080:8080 \
  ghcr.io/teddyzxcv/ntfy-mcp:latest

Using docker-compose:

version: "3.8"
services:
  ntfy-mcp:
    image: ghcr.io/teddyzxcv/ntfy-mcp:latest
    environment:
      - NTFY_BASE_URL=https://ntfy.sh
      - NTFY_TOPIC=project-alerts
      - PORT=8080
      - LOG_LEVEL=info
    ports:
      - "8080:8080"

Environment variables:

Example bare-metal startup (if binary is provided):

export NTFY_BASE_URL="https://ntfy.sh"
export NTFY_TOPIC="alerts"
export PORT=8080
./ntfy-mcp

API and Example Payloads

The server exposes a simple POST endpoint (e.g. /mcp/notify) that accepts a JSON payload. A minimal example:

Request:

POST /mcp/notify HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "title": "Model alert",
  "body": "High-confidence hallucination detected in conversation #123",
  "severity": "high",
  "meta": {
    "conversation_id": "123",
    "user": "alice"
  }
}

Behavior:

• “title” maps to the ntfy Title header
• “body” is sent as the notification body
• “severity” may influence ntfy priority headers (if configured)
• “meta” fields are appended to the body as JSON or as headers depending on configuration

Curl example sending the above:

curl -X POST http://localhost:8080/mcp/notify \
  -H "Content-Type: application/json" \
  -d '{"title":"Model alert","body":"High-confidence hallucination detected","severity":"high"}'

Available Resources

• Repository: https://github.com/teddyzxcv/ntfy-mcp
• ntfy server/docs: https://ntfy.sh
• MCP (Model Context Protocol) reference: check your MCP spec or integration docs for message schema guidance

These resources help with advanced customization like using a self-hosted ntfy instance, enabling authentication, or extending the message mapping.

Use Cases

• Model monitoring: Send immediate phone alerts when an LLM triggers a safety filter or when hallucination detectors fire, so an engineer can triage quickly.
• Job completion: Notify you when long-running batch inference or data processing jobs finish, including links or job IDs for follow-up.
• CI/CD events: Forward important build/test failures or security scan findings to a mobile alert channel for on-call responders.
• Home automation: Combine model-driven automation triggers with phone push notifications (e.g., anomaly detected by a model analyzing sensor data).
• Security & ops: Receive real-time alerts for suspicious activity detected by inference pipelines or rule-based monitors.

Example: notifying on an inference error

• The inference service posts an MCP message to /mcp/notify with title “Inference error”, body including logs and severity “critical”. The Ntfy MCP Server forwards this to the configured ntfy topic, pushing a notification to your mobile device(s).

Notes and Best Practices

• Use distinct topics for different alert categories (ops, security, user-notifications) to allow subscription control on clients.
• Protect the MCP endpoint in front of the server (authentication, network ACLs) if you accept messages from untrusted sources.
• Rate-limit alerts or aggregate related events to avoid notification fatigue.

For more details and advanced configuration, see the project’s GitHub repository: https://github.com/teddyzxcv/ntfy-mcp.