ntfy Blade MCP

Token-efficient MCP server for ntfy push notifications. Publish alerts, poll topics, manage tokens and reservations.

Requirements

• Python 3.12+
• A ntfy server (self-hosted or ntfy.sh)
• Optional: bearer token for authenticated access

Quick Start

# Install
uv sync

# Configure
export NTFY_BASE_URL=https://ntfy.sh
export NTFY_TOKEN=tk_your_token_here
export NTFY_DEFAULT_TOPIC=my-alerts
export NTFY_WRITE_ENABLED=true

# Run
uv run ntfy-blade-mcp

Tools (10)

Security Model

1. Environment gate — all write tools require NTFY_WRITE_ENABLED=true
2. Per-call confirmation — every write tool requires confirm=true
3. Token redaction — tokens are truncated in output (full token shown only on create)
4. PII scrubbing — bearer tokens and API keys redacted from error messages
5. No admin endpoints — user management excluded by design

Token Efficiency

• ntfy_info collapses 3 API calls (health + config + stats) into 1 tool call
• Pipe-delimited output, null-field omission, truncation at 200 chars
• Default priority (3) omitted from poll output
• NTFY_DEFAULT_TOPIC eliminates per-call topic specification

Environment Variables

Development

make install-dev   # Install with dev deps
make test          # Run unit tests
make check         # Lint + format + typecheck
make test-cov      # Tests with coverage

Architecture

src/ntfy_blade_mcp/
├── __init__.py
├── __main__.py      # Entry point
├── server.py        # FastMCP + 10 @mcp.tool definitions
├── client.py        # httpx async client for ntfy API
├── formatters.py    # Pipe-delimited token-efficient output
└── models.py        # Config, gates, constants, exceptions

Sidereal Marketplace

Contract: notifications-push-v1 — see sidereal-plugin.yaml.

Licence

MIT