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.
Rust MCP server and CLI for Gotify push notifications, with stdio/HTTP transports, auth, Claude/Codex plugin packaging, and npm/GitHub Release distribution.
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.
GOTIFY_*, GOTIFY_MCP_*, GOTIFY_RMCP_* for npm launcher controls
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.
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
Surface
Status
Entry point
Purpose
MCP stdio
Supported
rgotify mcp, npx -y @dinglebear/rgotify mcp
Local child-process MCP clients.
MCP HTTP
Supported
rgotify serve, POST /mcp
Streamable HTTP MCP for local or shared server deployments.
CLI
Supported
rgotify <command>
Scriptable parity and debugging.
Prompts
Supported
send_notification, check_status
Reusable agent prompts.
Resource
Supported
gotify://schema/mcp-tool
JSON schema for the gotify tool.
REST API
Not shipped
N/A
Gotify already owns the REST API.
Web UI
Not shipped
N/A
Gotify already owns the web UI.
MCP Tool Reference
One MCP tool is exposed: gotify. Pass the required action argument to select
the operation.
Read Actions
Action
Description
Required params
Optional params
health
Gotify server health check.
none
none
version
Gotify server version.
none
none
me
Current authenticated user.
none
none
messages
List messages.
none
app_id, limit, since
applications
List applications.
none
none
clients
List clients.
none
none
status
Return runtime status, config snapshot, and counters.
none
none
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
none
Destructive Actions
Destructive actions require confirm=true in MCP arguments, --confirm on the
CLI, or GOTIFY_ALLOW_DESTRUCTIVE=true in the process environment.
Action
Description
Required params
delete_message
Delete one message.
id, confirm
delete_all_messages
Delete all messages.
confirm
delete_application
Delete an application and its messages.
app_id, confirm
delete_client
Delete a client.
client_id, confirm
Meta, Prompts, And Resource
Primitive
Name / URI
Purpose
Tool action
help
Return built-in markdown tool help.
Prompt
send_notification
Guide an agent through a notification send.
Prompt
check_status
Check health and recent messages.
Resource
gotify://schema/mcp-tool
Return the current action-based JSON schema.
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.
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
Variable
Required
Description
GOTIFY_URL
yes
Gotify server base URL, for example https://gotify.example.com.
GOTIFY_CLIENT_TOKEN
for management
Gotify client token for read and management actions.
GOTIFY_APP_TOKEN
for send
Gotify app token used only to send notifications.
Runtime Variables
Variable
Default
Description
GOTIFY_ALLOW_DESTRUCTIVE
false
Skip destructive confirmation gates.
GOTIFY_MCP_HOST
0.0.0.0
HTTP MCP bind host.
GOTIFY_MCP_PORT
40020
HTTP MCP bind port.
GOTIFY_MCP_TOKEN
empty
Static bearer token for HTTP MCP when not in loopback dev mode.
GOTIFY_MCP_NO_AUTH
false
Disable HTTP MCP auth. Use only on loopback or behind a trusted gateway.
GOTIFY_MCP_AUTH_MODE
bearer
Set to oauth for Google OAuth through lab-auth.
GOTIFY_MCP_PUBLIC_URL
empty
Public URL for OAuth metadata and protected-resource discovery.
GOTIFY_MCP_GOOGLE_CLIENT_ID
empty
Google OAuth client ID.
GOTIFY_MCP_GOOGLE_CLIENT_SECRET
empty
Google OAuth client secret.
GOTIFY_MCP_AUTH_ADMIN_EMAIL
empty
Initial/admin OAuth email.
GOTIFY_MCP_AUTH_SQLITE_PATH
<data>/auth.db
OAuth state database path.
GOTIFY_MCP_AUTH_KEY_PATH
<data>/auth-jwt.pem
OAuth JWT signing key path.
GOTIFY_MCP_ALLOWED_HOSTS
empty
Comma-separated Host header allowlist.
GOTIFY_MCP_ALLOWED_ORIGINS
empty
Comma-separated Origin header allowlist.
GOTIFY_NOAUTH
false
Escape hatch permitting a non-loopback bind with no auth. See below.
GOTIFY_MCP_HOME
~/.gotify or /data
Override the appdata dir used by rgotify setup.
RUNNING_IN_CONTAINER
unset
Forces the /data appdata path.
RUST_LOG
info
Rust log filter. Stdio logs must stay off stdout.
GOTIFY_MCP is also the lab-auth env prefix, so lab-auth reads further
GOTIFY_MCP_* keys beyond those listed here.
Startup Bind Guard
The server refuses to start when it would bind a non-loopback host with no
authentication configured. To bind 0.0.0.0, set GOTIFY_MCP_TOKEN, or use
GOTIFY_MCP_AUTH_MODE=oauth, or — only when an upstream gateway genuinely
enforces auth — set GOTIFY_NOAUTH=true.
Authentication
Policy
When
Effect
Loopback development
GOTIFY_MCP_HOST starts with 127. or GOTIFY_MCP_NO_AUTH=true
No HTTP auth layer is mounted. Use for local testing only.
Static bearer
GOTIFY_MCP_TOKEN is set and the server is not loopback dev
/mcp requires Authorization: Bearer <token>.
OAuth
GOTIFY_MCP_AUTH_MODE=oauth plus Google OAuth settings
/mcp uses lab-auth OAuth and scoped bearer tokens.
Stdio
rgotify mcp
The local child-process boundary is the trust boundary.
MCP scopes are gotify:read and gotify:write. The static bearer token grants
both scopes. OAuth tokens are checked before MCP calls are dispatched.
Safety And Trust Model
MCP callers never provide Gotify client tokens, Gotify app tokens, OAuth
secrets, static bearer tokens, passwords, or API keys as tool arguments.
Upstream credentials are loaded from env/config only.
Delete actions require confirm=true, --confirm, or the explicit
GOTIFY_ALLOW_DESTRUCTIVE=true process override.
Gotify is the durable source of notification state; this server is a thin
projection over that API.
Stdio mode runs with the user's local permissions and is not a sandbox.
HTTP mode should not be exposed beyond loopback without bearer or OAuth auth
plus TLS from an upstream reverse proxy.
Architecture
MCP client / CLI
|
v
rgotify
|
+-- MCP shim: JSON args -> GotifyService -> structured result
+-- CLI shim: argv -> GotifyService -> stdout
|
v
GotifyService
|
v
GotifyClient
|
v
Gotify REST API
Path
Role
src/app.rs
Business service layer, destructive gate, response shaping.
src/gotify.rs
Gotify REST client.
src/mcp/
RMCP tool, prompts, resource, schema, and auth checks.
src/cli/
CLI parser, doctor, setup helpers, and output formatting.
src/config.rs
Env/config loading and defaults.
packages/gotify-rmcp/
npm launcher and release-binary downloader.
The thin-shim rule is intentional: MCP and CLI parse inputs, call
GotifyService, and return output. Credential handling, destructive gates, and
Gotify API behavior stay outside the MCP and CLI shims.
The container stores app data under /data, normally mounted from
${HOME}/.gotify.
Reverse Proxy
Expose only /mcp and /health. Preserve Streamable HTTP headers, require TLS,
and configure bearer or OAuth auth before exposing the server beyond loopback.
Plugin
The plugin ships no Claude Code hooks, so nothing runs setup for you. Run it
once by hand after installing or updating the plugin:
claude plugin install plugins/gotify
rgotify setup repair # create ~/.gotify and its .env, then re-check
rgotify setup install # copy the binary into ~/.local/bin so it is on PATH
rgotify setup check # read-only verification
rgotify setup repair creates the appdata dir and a placeholder .env;
rgotify setup install keeps a terminal-callable copy in ~/.local/bin (repeat
it after /plugin update). rgotify setup check verifies appdata, .env,
binary-on-PATH, and that port 40020 is free. The server itself takes its config
from the plugin's .mcp.json${user_config.*} block, so these commands
bootstrap the local environment rather than configure the server.
Troubleshooting
Symptom
Likely cause
Fix
401 from /mcp
Missing or wrong bearer/OAuth token.
Check GOTIFY_MCP_TOKEN and client headers, or use loopback dev mode locally.
CLI health fails
GOTIFY_URL is missing or unreachable.
Export GOTIFY_URL and confirm Gotify is reachable from this host.
send fails with auth error
Wrong token type.
Use GOTIFY_APP_TOKEN for send and GOTIFY_CLIENT_TOKEN for management.
Destructive action is blocked
Confirmation gate is working.
Add confirm=true, --confirm, or a deliberate GOTIFY_ALLOW_DESTRUCTIVE=true.
stdio MCP JSON parse errors
Logs went to stdout.
Keep protocol logs off stdout and lower RUST_LOG if needed.
npm launcher cannot find binary
Release asset download failed or was skipped.
Reinstall, check GOTIFY_RMCP_VERSION, or build rgotify from source.
Related Servers
soma - RMCP runtime for provider-backed MCP servers.
This README is curated. Generated or exhaustive catalogs should be refreshed in
their own files and treated as the source of truth for current branch details.
License
Original Dinglebear-authored portions of this project are licensed under AGPL-3.0-only. Separate commercial licensing is available for organizations that need terms outside the AGPL. Third-party material remains under its original license. See LICENSING.md.
R
Rgotify
dinglebear-ai·2 stars·
Rust MCP server and CLI for Gotify push notifications, with stdio/HTTP transports, auth, Claude/Codex plugin packaging, and npm/GitHub Release distribution.
No tool list yet. Remote servers get one after the first health check.
FAQ
Questions
How do I install Rgotify?
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
Does Rgotify need an API key?
The publisher lists these environment variables: GOTIFY_URL, GOTIFY_CLIENT_TOKEN, GOTIFY_APP_TOKEN, GOTIFY_RMCP_VERSION, GOTIFY_RMCP_REPO, GOTIFY_RMCP_RELEASE_BASE_URL, RUST_LOG.
What transport does Rgotify use?
Rgotify runs locally over stdio.
When was Rgotify last checked?
Last checked 2026-10-28. Rust MCP server and CLI for Gotify push notifications, with stdio/HTTP transports, auth, Claude/Codex plugin packaging, and npm/GitHub Release distribution.