gotify-rmcp

gotify-rmcp is a Rust MCP server and CLI for connecting agents to a self-hosted Gotify push notification server.

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 gotify-rmcp health --json -> start loopback HTTP with GOTIFY_MCP_HOST=127.0.0.1 npx -y gotify-rmcp 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

Surface	This repo
Repository	gotify-rmcp
Rust crate	gotify-mcp
Binary / CLI	rgotify
npm package	gotify-rmcp
npm binary aliases	gotify-rmcp, rgotify
MCP tool	gotify
Config home	~/.gotify on hosts, /data in containers
Env prefixes	GOTIFY_*, GOTIFY_MCP_*, GOTIFY_RMCP_* for npm launcher controls

The repo and npm package use the RMCP family name, while 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.

This repo owns	Gotify owns	Explicitly out of scope
MCP/CLI projection, request validation, auth policy, response shaping, setup checks, destructive gates.	Notification storage, delivery, Gotify users, token issuance, app/client state, upstream API semantics.	Notification scheduling, independent persistence, arbitrary webhook relay behavior, multi-tenant sandboxing, credential brokerage.

Install

Path	Command	Best for	Notes
npm / npx	npx -y gotify-rmcp --help	Local MCP clients and quick trials.	Downloads the matching rgotify binary from GitHub Releases.
Release installer	curl -fsSL https://raw.githubusercontent.com/jmagar/gotify-rmcp/main/scripts/install.sh | bash	Host installs without Node.	Installs rgotify for the current Linux host.
Docker / Compose	docker compose up -d	Shared HTTP MCP deployments.	Reads .env and exposes container port 40020.
Build from source	cargo build --release	Development and audits.	Produces target/release/rgotify.
Plugin	claude plugin install plugins/gotify	Claude Code local plugin setup from this checkout.	Uses the packaged setup hook and local runtime metadata.

npm / npx

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

npx -y gotify-rmcp --help
npx -y gotify-rmcp mcp
npx -y gotify-rmcp health --json

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

Variable	Purpose
GOTIFY_RMCP_SKIP_DOWNLOAD=1	Skip postinstall binary download.
GOTIFY_RMCP_VERSION or GOTIFY_RMCP_BINARY_VERSION	Select the GitHub Release tag.
GOTIFY_RMCP_REPO	Select the GitHub repo used for release downloads.
GOTIFY_RMCP_RELEASE_BASE_URL	Select a custom release base URL.

Build From Source

git clone https://github.com/jmagar/gotify-rmcp
cd gotify-rmcp
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:

Token	Env var	Used for
Client token	GOTIFY_CLIENT_TOKEN	Read and management actions such as messages, apps, clients, and current user.
App token	GOTIFY_APP_TOKEN	Sending notifications with send.

2. Run A Safe CLI Call

npx -y gotify-rmcp health --json

3. Start Loopback HTTP MCP

GOTIFY_MCP_HOST=127.0.0.1 npx -y gotify-rmcp 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

Surface	Status	Entry point	Purpose
MCP stdio	Supported	rgotify mcp, npx -y gotify-rmcp 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.

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 <message> [--title T] [--priority N] [--json]
rgotify create app <name> [--description D] [--priority N] [--json]
rgotify create client <name> [--json]

rgotify delete message <id> [--confirm] [--json]
rgotify delete all [--confirm] [--json]
rgotify delete app <app_id> [--confirm] [--json]
rgotify delete client <client_id> [--confirm] [--json]

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

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.
RUST_LOG	info	Rust log filter. Stdio logs must stay off stdout.

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.

Distribution Contract

Artifact	File(s)	Must align with
Rust crate/binary	Cargo.toml, Cargo.lock	Git tag, release assets, CLI docs, install scripts.
npm launcher	packages/gotify-rmcp/package.json, bin/rgotify.js, lib/platform.js, scripts/install.js	GitHub Release tag and assets named rgotify-x86_64.tar.gz and rgotify-windows-x86_64.tar.gz.
GitHub Releases	.github/workflows/*, scripts/install.sh	Package version, binary name, checksums, supported platforms.
Docker / Compose	config/Dockerfile, docker-compose*.yml	Exposed port 40020, healthcheck /health, env file contract.
MCP registry	server.json	Server identity tv.tootie/gotify-rmcp, env vars, transport URL, package version.
Plugin	plugins/gotify	Runtime command, setup hook, user config, bundled metadata.
Docs	README.md, docs/INVENTORY.md, docs/QUICKSTART.md	Current binary name, default port, action list, and env names.

Release invariant: npm package version, Rust crate version, server.json.version, GitHub Release tag, release asset names, and README install examples should move together. README examples must use canonical repo and binary names, not older aliases.

Development

cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release
npm --prefix packages/gotify-rmcp run check

Verification

# Binary and CLI
cargo build --release
./target/release/rgotify --version
GOTIFY_URL=https://gotify.example.com ./target/release/rgotify health --json

# HTTP health
GOTIFY_URL=https://gotify.example.com GOTIFY_MCP_HOST=127.0.0.1 ./target/release/rgotify serve
curl -sf http://127.0.0.1:40020/health

# MCP tool 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"}}}'

For live send or management tests, add GOTIFY_CLIENT_TOKEN and GOTIFY_APP_TOKEN from your Gotify instance.

Deployment

Docker / Compose

cp .env.example .env
$EDITOR .env
docker compose up -d
curl -sf http://127.0.0.1:40020/health

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

claude plugin install plugins/gotify
rgotify setup check

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

• unifi-rmcp / rustifi - UniFi controller REST API bridge.
• tailscale-rmcp / rustscale - Tailscale API bridge for devices, users, and tailnet operations.
• unraid-rmcp / unrust - Unraid GraphQL bridge for NAS and server management.
• apprise-rmcp - Apprise notification fan-out bridge for many delivery backends.
• arcane-rmcp - Arcane Docker management bridge for containers and related resources.
• yarr-rmcp - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.
• ytdl-mcp - Media download and metadata workflow server.
• synapse - Local Synapse workflow server for scout and flux actions.
• cortex - Syslog and homelab log aggregation MCP server.
• axon - RAG, crawl, scrape, extract, and semantic search project.
• lab - Homelab control plane and Labby gateway project.
• soma - RMCP scaffold/runtime template for new provider-backed servers.

Documentation

Start here:

• docs/QUICKSTART.md - focused setup flow.
• docs/INVENTORY.md - component inventory for actions, CLI commands, env vars, and endpoints.
• docs/RUST.md - Rust development notes.
• docs/stack/ARCH.md - stack architecture details.
• server.json - MCP registry metadata.
• packages/gotify-rmcp/README.md - npm package launcher notes.

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

MIT