Apprise RMCP

apprise-rmcp

通过 MCP 和 CLI 发送 Apprise 通知，支持经过身份验证的 stdio 和 HTTP 传输。

它提供一个 MCP 工具 apprise，以及 rapprise CLI。Agent 可以通过预配置的 Apprise 服务发送带标签的通知、发送一次性 Apprise URL 通知，并通过 stdio MCP、Streamable HTTP MCP 或直接执行 shell 命令检查上游服务的运行状况。

**30 秒快速路径：**运行 npx -y @dinglebear/rapprise health --json -> 使用 APPRISE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rapprise serve 启动本机环回 HTTP -> 使用 {"action":"health"} 调用 tools/call。

**状态：**可运行的 RMCP 上游客户端服务。具备写入能力；发送通知会产生有意的副作用。HTTP MCP 支持本机环回开发模式、静态承载令牌，以及通过 lab-auth 使用 Google OAuth。

**不适用于：**替代 Apprise API、在本仓库中存储通知目的地、安排提醒、构建通用 webhook 中继、多租户隔离，或通过 MCP 工具参数传递上游 Apprise 承载令牌。

目录

• 命名
• 功能与边界
• 安装
• 快速入门
• 客户端配置
• 运行时接口
• MCP 工具参考
• CLI 参考
• 配置
• 身份验证
• 安全与信任模型
• 架构
• 分发约定
• 开发
• 验证
• 部署
• 故障排除
• 相关服务
• 文档
• 许可证

命名

接口	本仓库
仓库	apprise-rmcp
Rust crate	apprise-mcp
二进制文件 / CLI	rapprise
npm 包	@dinglebear/rapprise
npm 二进制别名	apprise-rmcp、rapprise
MCP 工具	apprise
配置目录	主机上为 ~/.apprise，容器中为 /data
环境变量前缀	APPRISE_*、APPRISE_MCP_*、APPRISE_RMCP_*（用于 npm 启动器控制）

仓库和 npm 包使用 RMCP 系列名称，而发布的二进制文件使用简短的 Rust CLI 名称 rapprise。

功能与边界

• 通过上游 Apprise API 服务中配置的标签发送通知。
• 使用 notify_url 向 Apprise URL 方案发送一次性通知。
• 检查上游 Apprise API 的运行状况。
• 提供用于关键告警工作流的 send_alert 提示词。
• 提供用于本地插件 / 运行时检查的 setup 和 doctor 命令。

本仓库负责	Apprise 负责	明确不在范围内
MCP/CLI 接入、请求验证、身份验证策略、响应整形、设置检查和传输接线。	通知投递、已配置的目的地、标签、投递后端凭据、上游 API 语义。	目的地存储、日程安排、超出上游行为范围的重试策略、多租户隔离、任意 webhook 中继行为。

安装

路径	命令	适用场景	说明
npm / npx	npx -y @dinglebear/rapprise --help	Linux/Windows x86_64 客户端。	原子安装前会验证发布归档的 SHA-256。
发布安装程序	已验证的安装程序流程	没有 Node 的 Linux x86_64。	执行安装程序代码前会验证校验和及离线来源证明。
Docker / Compose	docker compose up -d	共享 HTTP MCP 部署。	读取 .env 并公开容器端口 40050。需要先创建外部网络——请参阅部署。
从源代码构建	cargo build --release	开发和审计。	生成 target/release/rapprise。
插件	just build-plugin && claude plugin install ./plugins/apprise	从此检出版本运行 Claude Code。	内置的 rapprise stdio 插件。不包含钩子。

发布版本会提供 SHA-256 文件和离线 GitHub 构建来源证明包。安装程序会通过 GitHub CLI 2.68+ 验证校验和及来源证明身份。 npm 启动器支持 x86_64 Linux 和 Windows 发布资源。

npm / npx

无需手动安装二进制文件，即可运行 stdio MCP 服务或 CLI：

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

npm 包会在 postinstall 期间下载 rapprise。仅在测试打包时覆盖下载行为：

变量	用途
APPRISE_RMCP_SKIP_DOWNLOAD=1	跳过 postinstall 二进制文件下载。
APPRISE_RMCP_VERSION or APPRISE_RMCP_BINARY_VERSION	选择 GitHub Release 标签。
APPRISE_RMCP_REPO	选择用于下载发布版本的 GitHub 仓库。
APPRISE_RMCP_RELEASE_BASE_URL	选择自定义发布基础 URL。

经过验证的二进制文件安装采用失败即关闭策略，并固定仓库、发布工作流和源代码标签。使用 npm 或发布安装程序前，请安装 gh 2.68 或更高版本。

已验证的发布安装程序

下载安装程序及其验证材料，但不要执行；然后在运行前验证完整性和来源证明：

将 version 替换为所需的发布标签；当前版本为 v0.2.0。

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

--repo 和 --signer-workflow 的值必须与构建时记录在证明中的身份相符。仓库迁移至 dinglebear-ai 组织之前发布的版本，其证明身份为 jmagar/rapprise；之后发布的版本请使用 dinglebear-ai/rapprise。

仅当安装了 GitHub CLI 2.68+ 且 gh.exe 位于 PATH 中时，npm 启动器才支持 Windows x86_64；不会跳过来源证明验证。

从源代码构建

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

最低支持的 Rust 版本：1.90。Rust edition 2021。Cargo 工作区包含两个成员：根目录下的 apprise-mcp 包和 xtask。

快速入门

1. 启动或指定 Apprise API

默认上游地址为 http://localhost:8000。

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

如果 API 服务位于其他位置，请使用 APPRISE_URL：

export APPRISE_URL=http://198.51.100.2:8766

仅当你的 Apprise API 服务要求 bearer 身份验证时，才设置 APPRISE_TOKEN：

export APPRISE_TOKEN=...

2. 运行安全的 CLI 调用

npx -y @dinglebear/rapprise health --json

3. 启动环回 HTTP MCP

APPRISE_MCP_HOST=127.0.0.1 npx -y @dinglebear/rapprise serve

在另一个 shell 中：

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

4. 进行首次 MCP 调用

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"}}}'

客户端配置

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

共享一个长期运行的服务时，可通过 Labby 将 Apprise 注册为 HTTP 上游；仅在本地使用时，也可直接以 stdio 方式运行。

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

通用 MCP JSON

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

不要将 APPRISE_TOKEN、OAuth 密钥、SSH 密钥、密码或上游 bearer 令牌放入 MCP 工具参数中。请使用环境变量、配置文件或 MCP 客户端的密钥存储。

运行时接口

接口	状态	入口点	用途
MCP stdio	支持	rapprise mcp, npx -y @dinglebear/rapprise mcp	本地子进程 MCP 客户端。
MCP HTTP	支持	rapprise serve, POST /mcp	适用于本地或共享服务部署的可流式传输 HTTP MCP。
存活状态	支持	GET /health	始终无需身份验证。
就绪状态 / 状态	支持	GET /ready, GET /status	受与 /mcp 相同的身份验证层保护。
OAuth 发现	有条件支持	/mcp/.well-known/* 和 lab-auth 路由	仅当 auth_mode = oauth 时挂载。
CLI	支持	rapprise <command>	提供可脚本化的同等功能和调试能力。
提示词	支持	send_alert	可重复使用的严重警报工作流。
REST API	未提供	N/A	REST API 已由 Apprise API 提供。
Web UI	未提供	N/A	Web UI 已由 Apprise API 提供。

MCP 工具参考

仅公开一个 MCP 工具：apprise。传入必需的 action 参数以选择 操作。

读取操作

操作	描述	必需参数	可选参数
health	检查 Apprise API 服务的运行状况。	无	无
status	返回经过身份验证的部署和运行时状态。	无	无
help	返回内置的 Markdown 工具帮助。	无	无

写入操作

操作	描述	必需参数	可选参数
notify	向已配置的 Apprise 标签发送通知；若省略 tag，则发送到所有已配置的服务。	body	tag, title, type
notify_url	向一个或多个 Apprise URL 方案发送无状态的一次性通知。	urls, body	title, type

通知类型

类型	含义
info	信息通知。
success	操作成功。
warning	非严重警告。
failure	严重故障或错误。

MCP 调用示例

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"}}}'

{
  "name": "apprise",
  "arguments": {
    "action": "notify",
    "body": "Deployment succeeded",
    "tag": "ops",
    "title": "Deploy complete",
    "type": "success"
  }
}

精选的操作摘要位于此处。添加自动生成的 docs/MCP_SCHEMA.md 之前，docs/INVENTORY.md 是完整参数的当前权威来源。

CLI 参考

CLI 调用与 MCP 工具相同的服务方法。

rapprise health [--json]
rapprise notify <body> [--tag TAG] [--title T] [--type info|success|warning|failure] [--json]
rapprise notify-url <urls> <body> [--title T] [--type info|success|warning|failure] [--json]

rapprise serve                          # Streamable HTTP MCP on :40050
rapprise serve mcp                      # same as `serve`
rapprise mcp                            # stdio MCP
rapprise doctor [--json]                # pre-flight environment validation
rapprise setup check                    # read-only audit of appdata/env
rapprise setup repair                   # idempotent: create missing setup files
rapprise setup install                  # copy this binary into ~/.local/bin
rapprise setup plugin-hook [--no-repair]

rapprise help                           # or --help / -h
rapprise --version                      # or -V

--json 会输出原始 JSON，而不是经过美化的字段。--help 会打印完整的环境变量参考。

配置

如果存在 config.toml，配置会先从该文件加载，然后由环境变量覆盖。 启动时会在主机上加载 ${APPRISE_HOME:-~/.apprise}/.env，在容器中加载 /data/.env。 参见完整清单。

上游变量

变量	必需	描述
APPRISE_URL	否	Apprise API 服务的基础 URL。默认值为 http://localhost:8000。
APPRISE_TOKEN	仅适用于受保护的上游服务	用于上游 Apprise API 的出站 bearer 令牌。与入站 APPRISE_MCP_TOKEN 不同。
APPRISE_MAX_CONCURRENT_REQUESTS	否	上游请求并发数。默认值为 32，范围为 1..=1024。
APPRISE_MAX_RESPONSE_BYTES	否	上游响应大小上限。默认值为 65536，范围为 1..=4194304。
APPRISE_HOME	否	数据目录。主机上的默认值为 ~/.apprise，容器中的默认值为 /data。

运行时变量

变量	默认值	描述
APPRISE_MCP_HOST	0.0.0.0	HTTP MCP 绑定主机。
APPRISE_MCP_PORT	40050	HTTP MCP 绑定端口。
APPRISE_MCP_TOKEN	empty	非环回开发模式下用于 HTTP MCP 的静态 bearer 令牌。
APPRISE_MCP_NO_AUTH	false	禁用 HTTP MCP 身份验证。仅用于环回地址或受信任的网关后方。
APPRISE_MCP_AUTH_MODE	bearer	设为 oauth，通过 lab-auth 使用 Google OAuth。
APPRISE_MCP_PUBLIC_URL	empty	用于 OAuth 元数据和受保护资源发现的公开 URL。
APPRISE_MCP_GOOGLE_CLIENT_ID	empty	Google OAuth 客户端 ID。
APPRISE_MCP_GOOGLE_CLIENT_SECRET	empty	Google OAuth 客户端密钥。
APPRISE_MCP_AUTH_ADMIN_EMAIL	empty	初始/管理员 OAuth 邮箱。
APPRISE_MCP_ALLOWED_HOSTS	empty	额外接受的 HTTP Host 值。
APPRISE_MCP_ALLOWED_ORIGINS	empty	HTTP MCP 的额外 CORS 来源。
APPRISE_MCP_AUTH_ALLOWED_REDIRECT_URIS	empty	OAuth 客户端重定向 URI。
APPRISE_MCP_AUTH_ALLOWED_EMAILS	empty	OAuth 邮箱允许列表。
APPRISE_MCP_AUTH_SQLITE_PATH	data-dir auth.db	OAuth 状态存储路径。
APPRISE_MCP_AUTH_KEY_PATH	data-dir auth-jwt.pem	JWT 签名密钥路径。
APPRISE_MCP_DISABLE_STATIC_TOKEN_WITH_OAUTH	true	禁止静态 bearer 令牌绕过 OAuth。
RUST_LOG	info	Rust 日志过滤器。Stdio 日志不得输出到 stdout。

令牌 TTL 和速率限制变量（APPRISE_MCP_AUTH_*_TTL_SECS、 APPRISE_MCP_AUTH_*_REQUESTS_PER_MINUTE、APPRISE_MCP_AUTH_MAX_PENDING_OAUTH_STATES） 详见 docs/INVENTORY.md。

身份验证

策略	适用情况	效果
Stdio	rapprise mcp	信任本地进程；HTTP 身份验证不适用。
环回开发	环回地址且无身份验证	允许未验证身份的本地 HTTP。
非环回无身份验证	非环回地址且无身份验证	无效；启动时必须拒绝。
静态 bearer	bearer 加 APPRISE_MCP_TOKEN	要求提供完全匹配的 bearer 令牌。
OAuth	issuer/client/admin 设置	要求使用 OAuth/JWT。
OAuth 静态令牌控制	disable-static 为 true	静态令牌不得绕过 OAuth。

MCP 作用域为 apprise:notify 和 apprise:admin。在分发 MCP 调用前会检查 OAuth 令牌。

安全与信任模型

• MCP 调用方绝不会将 APPRISE_TOKEN、OAuth 密钥、静态 bearer 令牌、 密码、SSH 密钥或 API 密钥作为工具参数提供。
• 上游 Apprise 凭据仅从环境变量/配置中加载。
• notify 是首选方式，因为目标地址已在上游按标签配置。
• notify_url 有意接受 MCP 参数中的 Apprise URL 模式，用于单次发送。请将这些 URL 视为敏感内容；如果已有按标签配置的上游目标地址，请避免使用此方式。
• Apprise API 是目标地址配置的持久数据源；此服务只是该 API 的轻量映射层。
• 除非通过上游反向代理提供 bearer 或 OAuth 身份验证以及 TLS，否则不应将 HTTP 模式暴露在环回地址之外。

架构

MCP client / CLI
       |
       v
rapprise
       |
       +-- MCP shim: JSON args -> AppriseService -> structured result
       +-- CLI shim: argv -> AppriseService -> stdout
       |
       v
AppriseService
       |
       v
AppriseClient
       |
       v
Apprise API server
       |
       v
Notification backends

路径	作用
src/app.rs	业务服务层、响应整形、计数器和通知调用。
src/apprise.rs	Apprise API REST 客户端。
src/mcp/	RMCP 工具、提示词、架构、路由和身份验证检查。
src/cli.rs	CLI 解析器、doctor/setup 辅助工具和输出格式化。
src/config.rs	环境变量/配置加载和默认值。
packages/apprise-rmcp/	npm 启动器和发布二进制下载器。

通知命令和 MCP 最终都会调用 AppriseService。目前 CLI 也负责 setup、doctor、自行安装、文件系统和输出编排；它并非纯粹的参数转发层。

分发契约

制品	文件	必须与以下内容保持一致
Rust crate/二进制文件	Cargo.toml、Cargo.lock	Git 标签、发布资产、CLI 文档、安装脚本。
npm 启动器	packages/apprise-rmcp/package.json、bin/rapprise.js、lib/platform.js、scripts/install.js	GitHub Release 标签，以及命名为 rapprise-x86_64.tar.gz 和 rapprise-windows-x86_64.tar.gz 的资产。
GitHub Releases	.github/workflows/*、scripts/install.sh、install.sh	软件包版本、二进制文件名、校验和、支持的平台。
Docker / Compose	config/Dockerfile、docker-compose.yml、docker-compose.prod.yml	暴露端口 40050、健康检查 /health、环境文件契约。
MCP 注册表	server.json	标识 ai.dinglebear/rapprise、stdio 软件包、版本。
插件	plugins/apprise	仅捆绑 rapprise stdio。不含 hooks、version 或清单中的 userConfig。
文档	README.md、docs/INVENTORY.md、docs/QUICKSTART.md	当前二进制文件名、默认端口、操作列表和环境变量名称。

发布不变量：npm、crate、注册表/服务元数据、清单、Git 标签和原生资产必须同步更新。Release Please 负责这些更新。

开发

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

# Contract checks
bash tests/docs-contract.sh              # docs, versions, and plugin invariants
bash scripts/validate-plugin-layout.sh   # or: just validate-plugin

just 封装了常见的开发循环：just check、just lint、just fmt、 just test、just release、just build-plugin、just docker-up、 just health。插件任务是 build-plugin——没有 plugin-build。

Cargo.toml 声明了 rmcp = "1.6.0"，但插入符版本范围会解析到更新版本， 而 Cargo.lock 锁定的是 rmcp 1.7.0。以锁文件为准。

验证

# Binary and CLI
cargo build --release
./target/release/rapprise --version
./target/release/rapprise health --json

# HTTP health
APPRISE_MCP_HOST=127.0.0.1 ./target/release/rapprise serve
curl -sf http://127.0.0.1:40050/health

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

要进行实时通知测试，请在 Apprise API 服务中至少配置一个目标，并使用其标签调用 notify。

部署

Docker / Compose

docker-compose.prod.yml 将 apprise-mcp 网络声明为 external: true， 因此请在首次启动前创建一次：

cp .env.example .env
$EDITOR .env
docker network create apprise-mcp
docker compose up -d
curl -sf http://127.0.0.1:40050/health

docker-compose.yml 使用 config/Dockerfile 构建 apprise-mcp:dev，并扩展生产服务。单独运行 docker-compose.prod.yml 时会以 pull_policy: never 运行已发布的镜像，因此请先拉取或加载该镜像。 容器以 UID 1000 只读运行，并将应用数据存储在 /data 下，通常挂载自 ${APPRISE_DATA_DIR:-${HOME}/.apprise}。使用 APPRISE_MCP_HOST_PORT 覆盖已发布的主机端口。

反向代理

仅公开 /mcp 和 /health——使用 OAuth 时，还需公开 lab-auth 和 /mcp/.well-known/* 路由。将 /ready 和 /status 保持为内部路由。保留 Streamable HTTP 标头，要求使用 TLS， 并在将服务暴露到回环地址以外之前配置 bearer 或 OAuth 身份验证。

插件

该插件捆绑为 stdio，不附带 Claude Code hooks——会话开始时不会自动运行任何内容，因此请自行运行一次设置：

just build-plugin
claude plugin install ./plugins/apprise
rapprise setup check

故障排除

症状	可能原因	解决方法
/mcp 返回 401	缺少 bearer/OAuth 令牌或令牌错误。	检查 APPRISE_MCP_TOKEN 和客户端标头，或在本地使用回环地址开发模式。
CLI 健康检查失败	无法访问 Apprise API。	检查 APPRISE_URL 和上游 Apprise API 服务。
notify 未发送到任何地方	没有上游目标与该标签匹配。	检查 Apprise API 中配置的标签，或省略 tag 以发送到所有已配置的服务。
notify_url 失败	Apprise URL 架构无效，或目标后端被阻止。	直接通过 Apprise API 测试该 URL；重复使用时优先选择已配置的标签。
stdio MCP JSON 解析错误	日志输出到了 stdout。	不要将协议日志输出到 stdout；必要时降低 RUST_LOG。
npm 启动器找不到二进制文件	发布资产下载失败或被跳过。	重新安装，检查 APPRISE_RMCP_VERSION，或从源代码构建 rapprise。

相关服务

• soma - 面向由提供商支持的 MCP 服务的 RMCP 运行时和脚手架。
• unifi-rmcp - UniFi 控制器 REST API 桥接工具。
• tailscale-rmcp - 面向设备、用户和 tailnet 操作的 Tailscale API 桥接工具。
• unraid - Unraid monorepo；unraid-rs/ 是 GraphQL MCP 桥接工具（二进制文件 runraid）。
• gotify-rmcp - 面向发送、消息、应用和客户端的 Gotify 推送通知桥接工具。
• arcane-rmcp - 面向容器及相关资源的 Arcane Docker 管理桥接工具。
• yarr - 面向 Sonarr、Radarr、Prowlarr、Plex 和相关服务的媒体栈桥接工具。
• ytdl-rmcp - 媒体下载和元数据工作流服务。
• synapse-rmcp - 用于 scout 和 flux 操作的本地 Synapse 工作流服务。
• cortex - Syslog 和家庭实验室日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - 家庭实验室控制平面和 MCP 网关项目。

文档

从这里开始：

• docs/QUICKSTART.md - 精简的设置流程。
• docs/INVENTORY.md - 操作、CLI 命令、环境变量和端点的组件清单。
• docs/README.md - 文档索引。
• server.json - MCP 注册表元数据。
• packages/apprise-rmcp/README.md - npm 包启动器说明。

本 README 经过精心整理。生成的或详尽的目录应在各自文件中更新，并作为当前分支详情的准确信息来源。

许可证

本项目中由 Dinglebear 编写的原创部分依据 AGPL-3.0-only 授权。对于需要 AGPL 之外授权条款的组织，可提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。