mcpField
G
gotify

gotify

github.com/wmy2981Productivity155 installsUpdated 5w ago
Repository

About gotify

gotify is a command-line client for managing a self-hosted Gotify server through its REST API. It is for users who send push notifications or manage message sources and receiving clients, and also supports message retrieval, plugin controls, and live WebSocket messages.

Key features

  1. 01Send notifications with titles and priorities
  2. 02Manage applications and receiving clients
  3. 03List and paginate through messages
  4. 04List, enable, or disable plugins
  5. 05Check server health and version
  6. 06Subscribe to live messages over WebSocket

Use cases

  1. 01Send deployment or backup notifications
  2. 02Manage Gotify apps and device clients
  3. 03Review recent or selected messages
  4. 04Receive and handle live message streams

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/wmy2981/skills --skill gotify

After installing, type/gotifyin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.claude-plugin/
plugin.json
references/
api_doc_spec.json
scripts/
.env.example
gotify_client.py

Details

From the project README

Gotify CLI Client

Send and manage push notifications on a self-hosted Gotify server via its REST API v2.0.2.

Execution Rule

Run the user's requested command directly without pre-checking dependencies, environment variables, or configuration. If something is wrong, the script will fail with a clear error — check and fix only then.

Environment Variables

VariableRequiredPurpose
GOTIFY_URL✅Server base URL, e.g. https://gotify.example.com
GOTIFY_CLIENT_TOKEN✅Client token — manage apps, clients, read messages
GOTIFY_APP_TOKEN✅Application token — send messages

The script loads these from ~/.wmyskills/.env (shared across skills) automatically; a scripts/.env in the script directory takes priority if present. Use scripts/.env.example as the template — add the variables to ~/.wmyskills/.env, never overwriting an existing file. Missing tokens produce a clear error; tokens can also be passed per-call via --token.

Requirements

# Core — stdlib only (no install needed)
# WebSocket (optional, for ws-subscribe only):
pip install websocket-client

Usage

Script: scripts/gotify_client.py

python scripts/gotify_client.py <command> [options]
🔔 Send a Notification
python scripts/gotify_client.py send \
  --message "Deployment succeeded" \
  --title "CI/CD Alert" \
  --priority 5
FlagRequiredDescription
--message / -m✅Message body (markdown supported)
--title / -tNotification title
--priority / -p0–10 (0=silent, 10=urgent; omitted → not sent, API uses 0)
--extrasJSON string for plugin-specific data
--tokenOverride app token

Extras example (Firebase push config):

python scripts/gotify_client.py send -m "Hello" --extras '{"firebase":{"priority":"high"}}'
📱 Applications (Message Sources)
# List all applications
python scripts/gotify_client.py list-apps

# Create a new application
python scripts/gotify_client.py create-app \
  --name "Backup Bot" \
  --description "Backup notifications" \
  --default-priority 3

# Delete an application
python scripts/gotify_client.py delete-app --id 5
create-app FlagRequiredDescription
--name✅Application name
--description / -dDescription
--default-priorityDefault message priority (0–10)
--imageApplication image URL
--internalMark as internal (flag, no value needed)

The returned token from create-app is the app token for sending messages. Store it securely.

📲 Clients (Receiving Devices)
# List all clients
python scripts/gotify_client.py list-clients

# Create a new client
python scripts/gotify_client.py create-client --name "iPhone"

# Delete a client
python scripts/gotify_client.py delete-client --id 3
📬 Messages
# List recent messages (default: 30)
python scripts/gotify_client.py list-messages --limit 50

# Pagination — get messages after ID 100
python scripts/gotify_client.py list-messages --since 100

# Use a specific token to list messages (app or client token)
python scripts/gotify_client.py list-messages --token <token>

# Delete a single message
python scripts/gotify_client.py delete-message --id 42

# Bulk delete: all messages with ID < 500
python scripts/gotify_client.py delete-messages --before 500

# Bulk delete from a specific app
python scripts/gotify_client.py delete-messages --app-id 3 --before 500
list-messages FlagDescription
--limitMax messages to return (1–200; default 30)
--sinceMessage ID offset — returns messages with ID > this value
--tokenOverride token (defaults to client token from env)
🔌 Plugins
# List installed plugins
python scripts/gotify_client.py list-plugins

# Enable a plugin
python scripts/gotify_client.py toggle-plugin --id 1

# Disable a plugin
python scripts/gotify_client.py toggle-plugin --id 1 --disable
❤️ Server Health & Version
# Health check
python scripts/gotify_client.py health

# Version info
python scripts/gotify_client.py version
📡 Real-Time WebSocket Stream

Subscribe to live messages (requires websocket-client):

pip install websocket-client
python scripts/gotify_client.py ws-subscribe
# Override token:
python scripts/gotify_client.py ws-subscribe --token <client-or-app-token>

Output is one JSON object per received message.

API Key Concepts

  • App token (GOTIFY_APP_TOKEN): for sending messages via /message
  • Client token (GOTIFY_CLIENT_TOKEN): for managing apps/clients/messages everywhere else
  • Token is passed via X-Gotify-Key header (script handles this automatically)

Troubleshooting

ErrorCauseFix
GOTIFY_URL not setMissing env varSet GOTIFY_URL=https://your-server
401 UnauthorizedWrong/missing tokenCheck which token type is needed; verify env var
403 ForbiddenClient token used on sendUse app token for /message
Connection refusedServer downRun health to verify
No app tokenToken not configuredSet GOTIFY_APP_TOKEN or use --token

Comments

Markdown supported