Gotify RMCP

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

Curated action summaries live here. The current branch source code and docs/INVENTORY.md are the source of truth for complete parameters until a generated docs/MCP_SCHEMA.md is added.

CLI Reference

The CLI calls the same service methods as the MCP tool.

rgotify health [--json]

rgotify version [--json] rgotify me [--json] rgotify messages [--app-id N] [--limit N] [--since N] [--json] rgotify applications [--json] rgotify clients [--json]

rgotify send [--title T] [--priority N] [--json] rgotify create app [--description D] [--priority N] [--json] rgotify update app [--name N] [--description D] [--priority N] [--json] rgotify create client [--json]

rgotify delete message [--confirm] [--json] rgotify delete all [--confirm] [--json] rgotify delete app [--confirm] [--json] rgotify delete client [--confirm] [--json]

rgotify serve rgotify serve mcp rgotify mcp rgotify doctor [--json] rgotify setup check [--json] rgotify setup repair [--json] rgotify setup install [--json] rgotify setup plugin-hook [--no-repair] [--json]

Hyphenated aliases are accepted for the two-word forms: create-app, update-app, create-client, delete-message, delete-all, delete-app, delete-client.

Known parity exception: MCP action=status is MCP-only observability. The CLI equivalent for operator checks is rgotify doctor --json.

Configuration

Configuration loads from config.toml when present, then environment variables override those values. On startup, the binary also loads ~/.gotify/.env on hosts or /data/.env in containers without overriding already-set variables.

Required Upstream Variables

| GOTIFY_APP_TOKEN | for send | Gotify app token used only to send notifications.