rgotify

# 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](#naming)
- [Capabilities And Boundaries](#capabilities-and-boundaries)
- [Install](#install)
- [Quickstart](#quickstart)
- [Client Configuration](#client-configuration)
- [Runtime Surfaces](#runtime-surfaces)
- [MCP Tool Reference](#mcp-tool-reference)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Authentication](#authentication)
- [Safety And Trust Model](#safety-and-trust-model)
- [Architecture](#architecture)
- [Distribution Contract](#distribution-contract)
- [Development](#development)
- [Verification](#verification)
- [Deployment](#deployment)
- [Troubleshooting](#troubleshooting)
- [Related Servers](#related-servers)
- [Documentation](#documentation)
- [License](#license)

## Naming

| Surface | This repo |
|---|---|
| Repository | `dinglebear-ai/rgotify` |
| Rust crate (Cargo package) | `gotify-mcp` |
| Binary / CLI | `rgotify` |
| npm package | `@dinglebear/rgotify` |
| npm binary aliases | `gotify-rmcp`, `rgotify` |
| MCP tool | `gotify` |
| MCP registry name | `ai.dinglebear/rgotify` |
| Config home | `~/.gotify` on hosts, `/data` in containers |
| Env prefixes | `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.

| 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 @dinglebear/rgotify --help` | Local MCP clients and quick trials. | Downloads the matching `rgotify` binary from GitHub Releases. |
| Release installer | `curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/rgotify/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. | Ships no hooks — run `rgotify setup repair` once by hand afterwards. |

### npm / npx

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

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

| 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

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

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

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

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

```bash
npx -y @dinglebear/rgotify health --json
```

### 3. Start Loopback HTTP MCP

```bash
GOTIFY_MCP_HOST=127.0.0.1 npx -y @dinglebear/rgotify serve
```

In another shell:

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

### 4. Make A First MCP Call

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

```json
{
  "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

```json
{
  "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.

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

### Generic MCP JSON

```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 @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 h