gotify-rmcp

MCP server and CLI for Gotify: send push notifications and manage messages, apps, and clients over stdio or streamable HTTP, with auth.

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

Related MCP server: mcp-gotify

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 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:

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 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

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

Runtime Variables

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

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

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

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

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

Related Servers

• soma - RMCP runtime for provider-backed MCP servers.

• unifi-rmcp - UniFi controller REST API bridge.

• tailscale-rmcp - Tailscale API bridge for devices, users, and tailnet operations.

• unraid - Unraid monorepo: GraphQL MCP bridges (runraid) and Unraid plugins.

• apprise-rmcp - Apprise notification fan-out bridge for many delivery backends.

• arcane-rmcp - Arcane Docker management bridge for containers and related resources.

• yarr - Media-stack bridge for Sonarr, Radarr, Prowlarr, Plex, and related services.

• ytdl-rmcp - Media download and metadata workflow server.

• synapse-rmcp - 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.

• labby - Homelab control plane and MCP gateway project.

• lumen - Local semantic code search MCP server.

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