gotify

gotify-mcp

Rust MCP server that bridges Claude (and other MCP clients) to a self-hosted Gotify push notification server. Send notifications, manage applications and clients, and query messages — all from Claude or the CLI.

Overview

Claude / MCP client
       │
       ▼
RMCP Streamable HTTP :9158/mcp   (or stdio for local clients)
       │
       ▼
  gotify-mcp (GotifyService)
       │  X-Gotify-Key header
       ▼
  Gotify REST API

The binary runs in three modes:

Mode	Invocation	Use case
HTTP MCP server	gotify or gotify serve	Claude Code, remote MCP clients
stdio MCP server	gotify mcp	Local child-process MCP clients
CLI	gotify <command>	Direct shell use

---

Token Model

Gotify uses two distinct token types. gotify-mcp requires both.

Token	Env var	Prefix	Used for
Client token	GOTIFY_CLIENT_TOKEN	C	Management: list, create, delete messages/apps/clients, read current user
App token	GOTIFY_APP_TOKEN	A	Sending messages (POST /message only)

The client token authorizes all read and management operations. The app token is used exclusively for send. Both must be set; if the app token is empty, send fails with an explicit error.

---

Quickstart

1. Create a Gotify client token and an app token in your Gotify web UI (or see docs/QUICKSTART.md).

2. Set environment variables:

export GOTIFY_URL=https://gotify.example.com
export GOTIFY_CLIENT_TOKEN=Cxxxxxxxxxxxxxxxx
export GOTIFY_APP_TOKEN=Axxxxxxxxxxxxxxxx

3. Run the MCP server:

# Build
cargo build --release

# HTTP MCP server (port 9158)
./target/release/gotify

# Or with an MCP bearer token
GOTIFY_MCP_TOKEN=my-secret ./target/release/gotify

4. Connect Claude Code (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gotify": {
      "type": "http",
      "url": "http://localhost:9158/mcp",
      "headers": {
        "Authorization": "Bearer my-secret"
      }
    }
  }
}

For stdio mode:

{
  "mcpServers": {
    "gotify": {
      "command": "/path/to/gotify",
      "args": ["mcp"],
      "env": {
        "GOTIFY_URL": "https://gotify.example.com",
        "GOTIFY_CLIENT_TOKEN": "Cxxxxxxxxxxxxxxxx",
        "GOTIFY_APP_TOKEN": "Axxxxxxxxxxxxxxxx"
      }
    }
  }
}

---

MCP Tool Reference

One MCP tool is exposed: gotify. Use the required action argument to select the operation.

Read actions

Action	Description	Required params	Optional params
health	Server health check (no auth)	—	—
version	Server version (no auth)	—	—
me	Current authenticated user	—	—
messages	List messages	—	app_id, limit (default 50), since
applications	List all applications	—	—
clients	List all clients	—	—

Write actions

Action	Description	Required params	Optional params
send	Send a push notification	message	title, priority, extras
create_application	Create an application	name	description, default_priority
update_application	Update an application	app_id	name, description, default_priority
create_client	Create a client	name	—

Destructive actions

These require either confirm=true in the call arguments or GOTIFY_ALLOW_DESTRUCTIVE=true in the environment. Without one of these, the call returns: "destructive operation — pass confirm=true or set GOTIFY_ALLOW_DESTRUCTIVE=true".

Action	Description	Required params
delete_message	Delete one message	id, confirm
delete_all_messages	Delete all messages	confirm
delete_application	Delete an application	app_id, confirm
delete_client	Delete a client	client_id, confirm

Meta

Action	Description
help	Returns built-in markdown documentation

MCP call examples (raw JSON-RPC)

# Health check
curl -s -X POST http://localhost:9158/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gotify","arguments":{"action":"health"}}}'

# Send a notification
curl -s -X POST http://localhost:9158/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer my-secret" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"gotify","arguments":{"action":"send","message":"Deploy complete","title":"CI","priority":5}}}'