gotify-mcp

Gotify MCP

MCP server for self-hosted Gotify. Exposes a unified gotify action router and a gotify_help companion tool for sending notifications and managing Gotify messages, applications, clients, and account metadata.

Overview

Two MCP tools are exposed:

Tool	Purpose
gotify	Unified action router for all Gotify operations
gotify_help	Returns markdown documentation for all actions and parameters

The server supports HTTP (default) and stdio transports. HTTP transport requires bearer authentication via GOTIFY_MCP_TOKEN.

What this repository ships

• gotify_mcp/server.py: FastMCP server, action router, and BearerAuth middleware
• gotify_mcp/services/gotify.py: Async HTTP client for the Gotify REST API
• skills/gotify/SKILL.md: Client-facing skill documentation
• docs/gotify-api.json: Bundled upstream Gotify API reference
• .claude-plugin/plugin.json, .codex-plugin/plugin.json, gemini-extension.json: Client manifests
• docker-compose.yml, Dockerfile, entrypoint.sh: Container deployment
• scripts/: Smoke tests and contract checks

Tools

gotify

Single entry point for all Gotify operations. Select the operation with the action parameter.

gotify(action="send_message", app_token="AbCdEf", message="Build finished", priority=5)

gotify_help

Returns the full action reference as Markdown. Call this to discover available actions.

gotify_help()

Actions

send_message

Send a push notification. Requires an app_token — this is the per-application token, not the client token.

Parameter	Type	Required	Default	Description
app_token	string	yes	—	Application token from Gotify UI (Settings > Apps)
message	string	yes	—	Notification body. Supports Markdown when extras sets contentType.
title	string	no	—	Notification title
priority	integer	no	app default	Priority 0–10. See Priority Levels below.
extras	dict	no	—	Extended metadata. See Extras Structure below.

Response fields:

Field	Type	Description
id	integer	Assigned message ID
appid	integer	Application ID that sent the message
message	string	Message body
title	string	Message title
priority	integer	Effective priority
date	string	ISO 8601 timestamp
extras	dict	Extras as submitted

Example:

gotify(action="send_message",
       app_token="AbCdEf",
       title="Deployment done",
       message="## Summary\n- All steps complete\n- Ready for review",
       priority=7,
       extras={"client::display": {"contentType": "text/markdown"}})

list_messages

List messages with pagination and optional filtering.

Parameter	Type	Required	Default	Description
app_id	integer	no	—	Filter to messages from one application
offset	integer	no	0	Cursor offset (message ID) — items before this ID are skipped
limit	integer	no	50	Maximum number of messages to return
sort_by	string	no	"id"	Field to sort by. Valid values: id, date, priority
sort_order	string	no	"desc"	"asc" or "desc"
query	string	no	""	Case-insensitive substring filter applied to title and message body

Response fields:

Field	Type	Description
items	array	Array of message objects (same shape as send_message response)
total	integer	Total messages before pagination
limit	integer	Limit used
offset	integer	Offset used
has_more	boolean	Whether more pages exist

Note: Gotify uses cursor-style pagination internally. The offset parameter maps to the since query parameter (a message ID), not a row count.

Example:

gotify(action="list_messages", limit=20, sort_order="desc")
gotify(action="list_messages", app_id=3, query="error", limit=10)

delete_message

Delete a single message by ID. Destructive — requires confirm=True.

Parameter	Type	Required	Default	Description
message_id	integer	yes	—	ID of the message to delete
confirm	boolean	yes	False	Must be True to proceed

Example:

gotify(action="delete_message", message_id=42, confirm=True)

delete_all_messages

Delete all messages across all applications. Destructive — requires confirm=True.