Ntfy Me MCP Server for AI Agents

Overview

Ntfy Me MCP Server is a lightweight bridge that lets AI agents send and receive ntfy notifications using the Model Context Protocol (MCP). It provides a simple, secure HTTP interface that translates MCP-style requests into ntfy messages and listens for ntfy events so agents can react to user replies or external signals. The server works with public ntfy services (like ntfy.sh) or self‑hosted ntfy instances, and it is built to be run locally, in CI, or on a server via npx or Docker.

This server is useful when you want agents to push short notifications (alerts, summaries, or prompts) to a user’s device and to receive callbacks or replies as structured events. By centralizing authentication and ntfy configuration, the MCP server removes the need for each agent to manage direct ntfy credentials or protocols.

Features

• Secure token-based authentication for MCP clients (agents)
• Send notifications to ntfy topics on behalf of agents
• Receive and forward ntfy events (replies, clicks) back to agents
• Works with public ntfy services or self-hosted ntfy endpoints
• Easy to run via npx for ad-hoc usage or Docker for production
• Minimal configuration via environment variables or CLI flags
• Lightweight HTTP API compatible with agent workflows

Installation / Configuration

Quick start (run with npx):

# Run directly from the repository via npx (one-off)
npx github:gitmotion/ntfy-me-mcp --port 8080 --ntfy-url https://ntfy.example.com --auth-token "SECRET_TOKEN"

Run via Docker (build locally and start):

# Build
docker build -t ntfy-me-mcp .

# Run with environment variables
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e NTFY_URL=https://ntfy.example.com \
  -e AUTH_TOKEN="SECRET_TOKEN" \
  ntfy-me-mcp

Configuration options (environment variables / CLI flags):

Example .env:

PORT=8080
NTFY_URL=https://ntfy.myselfhosted.instance
AUTH_TOKEN=super-secret-token
NTFY_TOPIC_PREFIX=agents/
LOG_LEVEL=info

Security notes:

• Keep AUTH_TOKEN confidential and rotate it regularly.
• If using a self-hosted ntfy instance, ensure TLS and firewall rules are configured appropriately.

Available Resources

• Repository: https://github.com/gitmotion/ntfy-me-mcp
• CLI: run via npx as shown above for development or ad-hoc runs
• Docker: build the image locally or use a provided image if available in the project registry
• HTTP API: a small set of endpoints to send notifications and receive events (examples below)
• Example client snippets (curl, JS) to integrate agent workflows

Example HTTP endpoints (illustrative):

• POST /mcp/notify — send a notification
• POST /mcp/events — webhook endpoint for inbound ntfy events (or server pushes events to connected agents)

Example send (curl):

curl -X POST "http://localhost:8080/mcp/notify" \
  -H "Authorization: Bearer SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "alerts/agent-123",
    "title": "Action required",
    "message": "Model X requests user approval for deployment",
    "priority": "high"
  }'

Example event payload delivered to agents (webhook / callback):

{
  "topic": "alerts/agent-123",
  "event_type": "reply",
  "message": "Approved. Proceed.",
  "metadata": {
    "ntfy_id": "abc123",
    "timestamp": "2026-04-10T12:34:56Z"
  }
}

Use Cases

• Agent notifications: an autonomous agent sends a short summary or decision prompt to a human operator. The operator replies via ntfy; the MCP server forwards the reply back to the agent so it can continue its workflow.
• Multi-agent orchestration: use the server as a central notification hub for multiple agents. Each agent posts to its topic; a human or service can monitor and respond without giving each agent direct ntfy credentials.
• Self-hosted privacy: organizations running a private ntfy instance can use Ntfy Me MCP Server to keep all message traffic within their infrastructure while exposing a small, authenticated API to internal agent workloads.
• Rapid prototyping: run quickly with npx during development to test agent-to-human