apprise-rmcp

Apprise notifications over MCP and CLI with authenticated stdio and HTTP transports.

It exposes one MCP tool, apprise, plus the rapprise CLI. Agents can send tagged notifications through a preconfigured Apprise server, run one-off Apprise URL sends, and check upstream health through stdio MCP, Streamable HTTP MCP, or direct shell commands.

30-second path: run npx -y @dinglebear/rapprise health --json -> start loopback HTTP with APPRISE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rapprise serve -> call tools/call with {"action":"health"}.

Status: operational RMCP upstream-client server. Write-capable; notification sends are intentional side effects. HTTP MCP supports loopback dev mode, static bearer tokens, and Google OAuth through lab-auth.

Not for: replacing Apprise API, storing notification destinations in this repo, scheduling reminders, building a generic webhook relay, multi-tenant isolation, or passing upstream Apprise bearer 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

The repo and npm package use the RMCP family name, while the shipped binary uses the short Rust CLI name rapprise.

Capabilities And Boundaries

• Send notifications through tags configured in the upstream Apprise API server.
• Send one-off notifications to Apprise URL schemas with notify_url.
• Check upstream Apprise API health.
• Expose the send_alert prompt for critical alert workflows.
• Provide setup and doctor commands for local plugin/runtime checks.

Install

Releases publish SHA-256 files and offline GitHub build-provenance bundles. The installers verify both the checksum and provenance identity with GitHub CLI 2.68+. The npm launcher supports x86_64 Linux and Windows release assets.

npm / npx

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

npx -y @dinglebear/rapprise --help
npx -y @dinglebear/rapprise mcp
npx -y @dinglebear/rapprise health --json

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

Verified binary installation is fail-closed and pins the repository, release workflow, and source tag. Install gh 2.68 or newer before using npm or the release installer.

Verified Release Installer

Download the installer and its verification material without executing it, then verify both integrity and provenance before running it:

Replace version with the release tag you want; v0.2.0 is current.

version=v0.2.0
base="https://github.com/dinglebear-ai/rapprise/releases/download/${version}/rapprise-installer.sh"
curl -fsSLO "$base"
curl -fsSLO "$base.sha256"
curl -fsSLO "$base.sigstore.json"
sha256sum --check rapprise-installer.sh.sha256
gh attestation verify rapprise-installer.sh \
  --repo dinglebear-ai/rapprise \
  --bundle rapprise-installer.sh.sigstore.json \
  --signer-workflow dinglebear-ai/rapprise/.github/workflows/release.yml \
  --source-ref "refs/tags/${version}" \
  --deny-self-hosted-runners
APPRISE_RMCP_VERSION="$version" bash rapprise-installer.sh

The --repo and --signer-workflow values must match the identity recorded in the attestation at build time. Releases cut before the repository moved to the dinglebear-ai org are attested as jmagar/rapprise; use dinglebear-ai/rapprise for releases cut afterwards.

The npm launcher supports Windows x86_64 only when GitHub CLI 2.68+ is installed and gh.exe is available on PATH; provenance verification is not skipped.

Build From Source

git clone https://github.com/dinglebear-ai/rapprise
cd rapprise
cargo build --release
./target/release/rapprise --help

Minimum supported Rust version: 1.90. Rust edition 2021. The Cargo workspace has two members: the root apprise-mcp package and xtask.

Quickstart

1. Start Or Point At Apprise API

The default upstream is http://localhost:8000.

docker run --rm -p 8000:8000 caronc/apprise:latest

Use APPRISE_URL when the API server is elsewhere:

export APPRISE_URL=http://198.51.100.2:8766

Set APPRISE_TOKEN only when your Apprise API server requires bearer auth:

export APPRISE_TOKEN=...

2. Run A Safe CLI Call

npx -y @dinglebear/rapprise health --json

3. Start Loopback HTTP MCP

APPRISE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rapprise serve

In another shell:

curl -sf http://127.0.0.1:40050/health

4. Make A First MCP Call

curl -s -X POST http://127.0.0.1:40050/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"apprise","arguments":{"action":"health"}}}'

Client Configuration

Claude Code Stdio

{
  "mcpServers": {
    "apprise": {
      "command": "npx",
      "args": ["-y", "apprise-rmcp", "mcp"],
      "env": {
        "APPRISE_URL": "http://localhost:8000"
      }
    }
  }
}

Claude Code HTTP

{
  "mcpServers": {
    "apprise": {
      "type": "http",
      "url": "http://127.0.0.1:40050/mcp",
      "headers": {
        "Authorization": "Bearer ${APPRISE_MCP_TOKEN}"
      }
    }
  }
}

Codex / Labby Gateway

Register Apprise through Labby as an HTTP upstream when sharing one long-running server, or run it directly as stdio for local-only use.

[mcp_servers.apprise]
command = "npx"
args = ["-y", "apprise-rmcp", "mcp"]

Generic MCP JSON

{
  "command": "rapprise",
  "args": ["mcp"],
  "env": {
    "APPRISE_URL": "http://localhost:8000"
  }
}

Do not put APPRISE_TOKEN, OAuth secrets, SSH keys, passwords, 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: apprise. Pass the required action argument to select the operation.

Read Actions

Write Actions