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	O

... View full README on GitHub