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)
| Tool | Type | Description |
|---|---|---|
ntfy_info |
read | Server health + capabilities + stats (3-in-1) |
ntfy_account |
read | Usage limits, reserved topics, active tokens |
ntfy_poll |
read | Poll topic(s) for cached messages |
ntfy_publish |
write | Send notification (priority, tags, actions, markdown, delay) |
ntfy_cancel |
write | Cancel a scheduled message |
ntfy_reserve |
write | Reserve a topic (set ACL) |
ntfy_unreserve |
write | Release a topic reservation |
ntfy_token_create |
write | Create a new API token |
ntfy_token_extend |
write | Extend/relabel a token |
ntfy_token_revoke |
write | Revoke a token |
Security Model
- Environment gate — all write tools require
NTFY_WRITE_ENABLED=true - Per-call confirmation — every write tool requires
confirm=true - Token redaction — tokens are truncated in output (full token shown only on create)
- PII scrubbing — bearer tokens and API keys redacted from error messages
- No admin endpoints — user management excluded by design
Token Efficiency
ntfy_infocollapses 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_TOPICeliminates per-call topic specification
Environment Variables
| Variable | Required | Secret | Description |
|---|---|---|---|
NTFY_BASE_URL |
yes | no | ntfy server URL |
NTFY_TOKEN |
no | yes | Bearer token (tk_...) |
NTFY_DEFAULT_TOPIC |
no | no | Default topic for publish/poll |
NTFY_WRITE_ENABLED |
no | no | Enable write operations |
TRANSPORT |
no | no | stdio (default) or http |
NTFY_MCP_PORT |
no | no | HTTP port (default: 8773) |
NTFY_MCP_API_TOKEN |
no | yes | HTTP transport bearer auth |
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
ntfy_blade_mcp-0.2.0.tar.gz
(91.9 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ntfy_blade_mcp-0.2.0.tar.gz.
File metadata
- Download URL: ntfy_blade_mcp-0.2.0.tar.gz
- Upload date:
- Size: 91.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b8b4cbada6248ddf0eaf3e2713ff618ce5a890effb2550df0f8e6ee123501861
|
|
| MD5 |
441bf0da0a688967886439c7c171a5bc
|
|
| BLAKE2b-256 |
122b9332937f035d8951cc8856d53f12b6a9f1f9a4e935e071b90a26a5e3e929
|
Provenance
The following attestation bundles were made for ntfy_blade_mcp-0.2.0.tar.gz:
Publisher:
publish.yml on Groupthink-dev/ntfy-blade-mcp
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ntfy_blade_mcp-0.2.0.tar.gz -
Subject digest:
b8b4cbada6248ddf0eaf3e2713ff618ce5a890effb2550df0f8e6ee123501861 - Sigstore transparency entry: 1396169068
- Sigstore integration time:
-
Permalink:
Groupthink-dev/ntfy-blade-mcp@90cdd5809f1c5411aec1cf01175164cb5810f90e -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/Groupthink-dev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@90cdd5809f1c5411aec1cf01175164cb5810f90e -
Trigger Event:
push
-
Statement type:
File details
Details for the file ntfy_blade_mcp-0.2.0-py3-none-any.whl.
File metadata
- Download URL: ntfy_blade_mcp-0.2.0-py3-none-any.whl
- Upload date:
- Size: 12.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4b25e9ec6eab30d73790d1ced6632641f4fbf24f8f7a4a5b1e925efd8ed461f3
|
|
| MD5 |
1a1be4b8a0953268a4bbabd01788dbbc
|
|
| BLAKE2b-256 |
cfb7d7042500d48ab728950024512dd9e8a10448492962d8b66125c76baab2e9
|
Provenance
The following attestation bundles were made for ntfy_blade_mcp-0.2.0-py3-none-any.whl:
Publisher:
publish.yml on Groupthink-dev/ntfy-blade-mcp
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
ntfy_blade_mcp-0.2.0-py3-none-any.whl -
Subject digest:
4b25e9ec6eab30d73790d1ced6632641f4fbf24f8f7a4a5b1e925efd8ed461f3 - Sigstore transparency entry: 1396169076
- Sigstore integration time:
-
Permalink:
Groupthink-dev/ntfy-blade-mcp@90cdd5809f1c5411aec1cf01175164cb5810f90e -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/Groupthink-dev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@90cdd5809f1c5411aec1cf01175164cb5810f90e -
Trigger Event:
push
-
Statement type:
