gotify-rmcp

Gotify notifications and app, client, and message management over MCP and CLI.

It exposes one MCP tool, gotify, plus the rgotify CLI. Agents can send notifications, inspect server health, list messages, and manage Gotify apps and clients through stdio MCP, Streamable HTTP MCP, or direct shell commands.

30-second path: set GOTIFY_URL, then run npx -y @dinglebear/rgotify health --json -> start loopback HTTP with GOTIFY_MCP_HOST=127.0.0.1 npx -y @dinglebear/rgotify serve -> call tools/call with {"action":"health"}.

Status: operational RMCP upstream-client server. Write-capable; destructive delete actions are gated by explicit confirmation. HTTP MCP supports loopback dev mode, static bearer tokens, and Google OAuth through lab-auth.

Not for: replacing Gotify, storing notifications independently, generic webhook routing, scheduling reminders, multi-tenant isolation, or passing Gotify tokens through MCP tool arguments.

Contents

• Naming
• Capabilities And Boundaries
• Install
• Quickstart
• Client Configuration
• Runtime Surfaces
• MCP Tool Reference
• CLI Reference
• Configuration
• Authentication
• Safety And Trust Model
• Architecture
• Distribution Contract
• Development
• Verification
• Deployment
• Troubleshooting
• Related Servers
• Documentation
• License

Naming

These names intentionally differ. The npm package and registry entry use the RMCP family name, the Cargo package is gotify-mcp, the git repo is rgotify, and the shipped binary uses the short Rust CLI name rgotify.

Capabilities And Boundaries

• Send Gotify push notifications with message, title, priority, and extras.
• Read server health, runtime status, server version, current user, messages, applications, and clients.
• Create or update applications and create clients.
• Delete messages, all messages, applications, or clients only after explicit destructive confirmation.
• Expose MCP prompts for common workflows and a resource containing the current tool schema.

Install

npm / npx

Run the stdio MCP server or CLI without a manual binary install:

npx -y @dinglebear/rgotify --help
npx -y @dinglebear/rgotify mcp
npx -y @dinglebear/rgotify health --json

The npm package downloads rgotify during postinstall. Override download behavior only when testing packaging:

Build From Source

git clone https://github.com/dinglebear-ai/rgotify
cd rgotify
cargo build --release
./target/release/rgotify --help

Minimum supported Rust version: 1.86.

Quickstart

1. Configure Gotify

For the safest first call, only GOTIFY_URL is required:

export GOTIFY_URL=https://gotify.example.com

Create tokens in the Gotify web UI before using management or send actions:

export GOTIFY_CLIENT_TOKEN=Cxxxxxxxxxxxxxxxx
export GOTIFY_APP_TOKEN=Axxxxxxxxxxxxxxxx

Token roles:

2. Run A Safe CLI Call

npx -y @dinglebear/rgotify health --json

3. Start Loopback HTTP MCP

GOTIFY_MCP_HOST=127.0.0.1 npx -y @dinglebear/rgotify serve

In another shell:

curl -sf http://127.0.0.1:40020/health

4. Make A First MCP Call

curl -s -X POST http://127.0.0.1:40020/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gotify","arguments":{"action":"health"}}}'

Client Configuration

Claude Code Stdio

{
  "mcpServers": {
    "gotify": {
      "command": "npx",
      "args": ["-y", "gotify-rmcp", "mcp"],
      "env": {
        "GOTIFY_URL": "https://gotify.example.com",
        "GOTIFY_CLIENT_TOKEN": "Cxxxxxxxxxxxxxxxx",
        "GOTIFY_APP_TOKEN": "Axxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code HTTP

{
  "mcpServers": {
    "gotify": {
      "type": "http",
      "url": "http://127.0.0.1:40020/mcp",
      "headers": {
        "Authorization": "Bearer ${GOTIFY_MCP_TOKEN}"
      }
    }
  }
}

Codex / Labby Gateway

Register Gotify through Labby as an HTTP upstream when sharing one long-running server, or run it directly as stdio for local-only use.

[mcp_servers.gotify]
command = "npx"
args = ["-y", "gotify-rmcp", "mcp"]

Generic MCP JSON

{
  "command": "rgotify",
  "args": ["mcp"],
  "env": {
    "GOTIFY_URL": "https://gotify.example.com"
  }
}

Do not put API keys, passwords, OAuth secrets, SSH keys, Gotify client tokens, Gotify app tokens, or upstream bearer tokens in MCP tool arguments. Use env, config files, or the MCP client's secret storage.

Runtime Surfaces

MCP Tool Reference

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

Read Actions

Write Actions

Destructive Actions

Destructive actions require confirm=true in MCP arguments, --confirm on the CLI, or GOTIFY_ALLOW_DESTRUCTIVE=true in the process environment.

Meta, Prompts, And Resource