Self-hosted ntfy push notification server with an integrated MCP sidecar, designed for the Beacon service mesh.

Claude (or any MCP client) can send push notifications to your phone, desktop, or any ntfy subscriber — just by calling a tool.

┌──────────────────────────────────┐
│  ntfy-mcp container  (mcp-net)  │
│                                  │
│  ntfy serve        → :8080       │  push notification server (Go)
│  mcp-sidecar       → :9099 tcp  │  MCP streamable HTTP endpoint
│  beacon announce   → :9099 udp  │  auto-discovery on mcp-net
└──────────────────────────────────┘
         │                    │
    ntfy clients         Beacon aggregator
  (phone, browser)      (http://localhost:9099/mcp)

Single container, two static Go binaries, no runtime dependencies.

• Docker
• Beacon running on mcp-net (see Beacon README)

docker network create mcp-net

cd ntfy
docker compose up -d --build

Check the Beacon web UI at http://localhost:9300 — the ntfy server should appear with its tools.

Or test directly:

# Send a test notification via ntfy
curl -d "Hello from ntfy-mcp!" http://localhost:8080/test

# Check MCP health
curl http://localhost:9099/mcp

Install the ntfy app on your phone or use the web UI at http://localhost:8080 and subscribe to a topic.

Once discovered by Beacon, these tools are available as ntfy__<tool_name>:

{
  "topic": "alerts",
  "message": "Build failed on main",
  "title": "CI Alert",
  "priority": 4,
  "tags": ["warning", "build"],
  "click": "https://github.com/org/repo/actions",
  "actions": [
    { "action": "view", "label": "Open CI", "url": "https://ci.example.com" }
  ]
}

Parameters:

{
  "topic": "photos",
  "url": "https://example.com/screenshot.png",
  "caption": "Latest dashboard screenshot"
}

{
  "topic": "alerts",
  "since": "1h",
  "limit": 10
}

No parameters. Returns ntfy server version, uptime, and topic count.

services:
  ntfy:
    build: .
    hostname: ntfy
    ports:
      - "8080:8080"   # ntfy web UI + API (optional, for direct access)
    expose:
      - "9099/tcp"     # MCP endpoint (Beacon discovers this)
      - "9099/udp"     # Beacon discovery
    environment:
      - NTFY_DEFAULT_TOPIC=general
    volumes:
      - ntfy-cache:/var/cache/ntfy   # optional persistence
    networks:
      - mcp-net

volumes:
  ntfy-cache:

networks:
  mcp-net:
    external: true

For public-facing deployments behind nsl.sh:

Internet → nsl.sh (HTTPS) → nginx-hash-lock (:8080) → ntfy (:8080)
                                    │
                              hash-based auth

• ntfy stays unauthenticated inside the Docker network
• nginx-hash-lock handles public access control via query parameter hash
• Beacon network is never exposed — MCP tools remain local-only
• ntfy clients (phone app) connect through the public nsl.sh URL with the auth hash

See Nginx-hash-lock for proxy configuration.

Once Beacon is running, ntfy tools are automatically available through the Beacon aggregator:

{
  "mcpServers": {
    "beacon": {
      "type": "streamableHttp",
      "url": "http://localhost:9099/mcp"
    }
  }
}

Or via CLI:

claude mcp add beacon --transport http http://localhost:9099/mcp

Tools appear as ntfy__send_message, ntfy__send_photo, etc.

MIT