gotify

Gotify — Push Notification Server

Gotify is a self-hosted push notification server. The gotify-mcp bridge exposes it as a single MCP tool (gotify) with action-based dispatch. A CLI binary and direct REST API are available as fallbacks.

Token model (critical — read this first)

Two tokens, two purposes. Using the wrong token returns 401.

Token	Env var	Starts with	Used for
Client token	GOTIFY_CLIENT_TOKEN	C	All management: list/create/delete apps, clients, messages; read user
App token	GOTIFY_APP_TOKEN	A	Sending only — POST /message

health and version need no token at all.

---

Tier 1 — MCP tool gotify (preferred)

Single tool, action selects the operation. All other parameters are optional unless noted.

Read actions

Action	Parameters	Notes
health	—	No auth required
version	—	No auth required
me	—	Returns current user info
messages	app_id?, limit? (default 50), since?	since is a message-ID cursor for pagination
applications	—	Returns array with id, name, defaultPriority, token
clients	—	Returns array with id, name, token

Write actions

Action	Required	Optional
send	message	title, priority (0–10), extras (object)
create_application	name	description, default_priority
update_application	app_id	name, description, default_priority
create_client	name	—

Destructive actions — require confirm=true

These will fail unless confirm=true is passed or GOTIFY_ALLOW_DESTRUCTIVE=true is set in the environment. Always confirm with the user before passing confirm=true, especially for delete_all_messages.

Action	Required	What it does
delete_message	id, confirm=true	Deletes one message
delete_all_messages	confirm=true	Wipes all messages — irreversible
delete_application	app_id, confirm=true	Deletes application and its token
delete_client	client_id, confirm=true	Deletes client and its token

Meta

• help — Returns full built-in documentation.

Examples

# Send an urgent alert
gotify(action="send", message="Disk usage at 95%", title="ALERT", priority=8)

# Send with rich extras (markdown content)
gotify(action="send", message="Build failed", title="CI", priority=5,
       extras={"client::display": {"contentType": "text/markdown"}})

# Check server health
gotify(action="health")

# List last 20 messages
gotify(action="messages", limit=20)

# Messages from a specific app only
gotify(action="messages", app_id=3, limit=10)

# Paginate: messages after ID 100
gotify(action="messages", since=100)

# Discover apps and their IDs
gotify(action="applications")

# Who am I?
gotify(action="me")

# Create a monitoring application
gotify(action="create_application", name="Monitoring", description="System alerts", default_priority=5)

# Update an app's default priority
gotify(action="update_application", app_id=2, default_priority=8)

# Delete a specific message (user confirmed)
gotify(action="delete_message", id=42, confirm=True)

# Wipe all messages (user explicitly confirmed)
gotify(action="delete_all_messages", confirm=True)

# Delete an app
gotify(action="delete_application", app_id=3, confirm=True)

# Create a client token for a new subscriber
gotify(action="create_client", name="HomeAssistant")

# Delete a client
gotify(action="delete_client", client_id=2, confirm=True)

---

Tier 2 — CLI binary (secondary)

Binary: ~/workspace/rustify/target/release/rgotify (or /usr/local/bin/rgotify in Docker)

Add --json to any command for raw JSON output. Add --confirm to destructive commands.

# Server info
rgotify health
rgotify version
rgotify me

# Messages
rgotify messages                           # last 50
rgotify messages --limit 20
rgotify messages --app-id 3               # filter by app
rgotify messages --since 100              # cursor pagination
rgotify messages --json                   # raw JSON

# Applications
rgotify applications

# Send a notification
rgotify send "Server rebooted" --title "Alert" --priority 8

# Create / delete apps
rgotify create app "Monitoring" --description "System alerts" --priority 5
rgotify create-app "Monitoring"           # short alias
rgotify delete app 3 --confirm
rgotify delete-app 3 --confirm            # short alias

# Delete messages
rgotify delete message 42 --confirm
rgotify delete-message 42 --confirm       # short alias
rgotify delete all --confirm              # wipe everything
rgotify delete-all --confirm              # short alias

# Clients
rgotify clients
rgotify create client "MyApp"
rgotify create-client "MyApp"             # short alias
rgotify delete client 2 --confirm
rgotify delete-client 2 --confirm         # short alias

---

Tier 3 — Direct REST API (fallback)

Use when neither the MCP tool nor the CLI binary is available.

Auth header: X-Gotify-Key: <token>

# No-auth endpoints
curl "$GOTIFY_URL/health"
curl "$GOTIFY_URL/version"

# Send a notification — uses APP token
curl -X POST "$GOTIFY_URL/message" \
  -H "X-Gotify-Key: $GOTIFY_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Server rebooted","title":"Alert","priority":5}'

# List messages — uses CLIENT token
curl "$GOTIFY_URL/message?limit=20" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

# Messages for a specific app
curl "$GOTIFY_URL/application/3/message?limit=10" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

# List applications
curl "$GOTIFY_URL/application" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

# List clients
curl "$GOTIFY_URL/client" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

# Current user
curl "$GOTIFY_URL/current/user" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

# Create application
curl -X POST "$GOTIFY_URL/application" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Monitoring","description":"System alerts","defaultPriority":5}'

# Update application
curl -X PUT "$GOTIFY_URL/application/2" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"defaultPriority":8}'

# Delete one message
curl -X DELETE "$GOTIFY_URL/message/42" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

# Delete all messages
curl -X DELETE "$GOTIFY_URL/message" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

# Delete application
curl -X DELETE "$GOTIFY_URL/application/3" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

# Create client
curl -X POST "$GOTIFY_URL/client" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"HomeAssistant"}'

# Delete client
curl -X DELETE "$GOTIFY_URL/client/2" \
  -H "X-Gotify-Key: $GOTIFY_CLIENT_TOKEN"

---

Gotchas

1. Wrong token = 401. send uses GOTIFY_APP_TOKEN. Everything else uses GOTIFY_CLIENT_TOKEN. Do not mix them.

2. Destructive gate. Delete operations require confirm=True (MCP) or --confirm (CLI) unless GOTIFY_ALLOW_DESTRUCTIVE=true is set. The error message when missing is: "destructive operation — pass confirm=true or set GOTIFY_ALLOW_DESTRUCTIVE=true".

3. Priority scale. 0 = silent/low, 5 = normal, 8+ = high/urgent. The Gotify Android client shows heads-up notifications at priority ≥ 8. Default is whatever the application's defaultPriority is set to.

4. delete_all_messages is irreversible. Always confirm with the user before passing confirm=True.

5. extras for rich content. Pass an object like {"client::display": {"contentType": "text/markdown"}} to render markdown in compatible clients. See Gotify extras docs for the full spec.

6. Pagination. messages returns up to limit items. The response includes a paging.next cursor — pass it as since to fetch the next page.

7. MCP server port. Runs on 9158 by default (GOTIFY_MCP_PORT to override).

8. No-auth endpoints. health and version work without any token — useful for liveness probes.

9. update_application is a PATCH-style PUT. Only fields you include are updated; omitted fields keep their current values.