Gotify RMCP

gotify-rmcp

通过 MCP 和命令行管理 Gotify 通知、应用、客户端和消息。

它提供一个 MCP 工具 gotify，以及 rgotify 命令行工具。Agent 可以通过 stdio MCP、Streamable HTTP MCP 或直接执行 Shell 命令发送通知、检查服务健康状态、列出消息，以及管理 Gotify 应用和客户端。

**30 秒快速上手：**设置 GOTIFY_URL，然后运行 npx -y @dinglebear/rgotify health --json -> 使用 GOTIFY_MCP_HOST=127.0.0.1 npx -y @dinglebear/rgotify serve 启动环回 HTTP -> 使用 {"action":"health"} 调用 tools/call。

**状态：**可运行的 RMCP 上游客户端服务。支持写入；删除等破坏性操作必须经过明确确认。HTTP MCP 支持环回开发模式、静态承载令牌，以及通过 lab-auth 使用 Google OAuth。

**不适用于：**替代 Gotify、独立存储通知、通用 Webhook 路由、安排提醒、实现多租户隔离，或通过 MCP 工具参数传递 Gotify 令牌。

目录

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

命名

方式	本仓库中的名称
仓库	dinglebear-ai/rgotify
Rust crate（Cargo 包）	gotify-mcp
二进制文件 / 命令行工具	rgotify
npm 包	@dinglebear/rgotify
npm 二进制别名	gotify-rmcp、rgotify
MCP 工具	gotify
MCP 注册表名称	ai.dinglebear/rgotify
配置目录	主机上为 ~/.gotify，容器中为 /data
环境变量前缀	npm 启动器控制项使用 GOTIFY_*、GOTIFY_MCP_*、GOTIFY_RMCP_*

这些名称有意采用不同形式。npm 包和注册表条目使用 RMCP 系列名称，Cargo 包名为 gotify-mcp，Git 仓库名为 rgotify，而发布的二进制文件使用简短的 Rust 命令行名称 rgotify。

功能与边界

• 发送 Gotify 推送通知，可设置消息、标题、优先级和附加内容。
• 读取服务健康状态、运行状态、服务版本、当前用户、消息、应用和客户端。
• 创建或更新应用，以及创建客户端。
• 只有经过明确的破坏性操作确认后，才能删除消息、所有消息、应用或客户端。
• 提供适用于常见工作流的 MCP 提示词，以及包含当前工具架构的资源。

本仓库负责	Gotify 负责	明确不在范围内
MCP/命令行映射、请求验证、身份验证策略、响应整理、设置检查、破坏性操作限制。	通知存储与投递、Gotify 用户、令牌签发、应用/客户端状态、上游 API 语义。	通知调度、独立持久化、任意 Webhook 中继行为、多租户隔离、凭据代理。

安装

路径	命令	适用场景	说明
npm / npx	npx -y @dinglebear/rgotify --help	本地 MCP 客户端和快速试用。	从 GitHub Releases 下载匹配的 rgotify 二进制文件。
Release 安装程序	curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/rgotify/main/scripts/install.sh | bash	无需 Node 的主机安装。	为当前 Linux 主机安装 rgotify。
Docker / Compose	docker compose up -d	共享的 HTTP MCP 部署。	读取 .env 并公开容器端口 40020。
从源代码构建	cargo build --release	开发和审计。	生成 target/release/rgotify。
插件	claude plugin install plugins/gotify	从此检出目录进行 Claude Code 本地插件设置。	不附带钩子——之后请手动运行一次 rgotify setup repair。

npm / npx

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

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

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

变量	用途
GOTIFY_RMCP_SKIP_DOWNLOAD=1	跳过 postinstall 二进制文件下载。
GOTIFY_RMCP_VERSION 或 GOTIFY_RMCP_BINARY_VERSION	选择 GitHub Release 标签。
GOTIFY_RMCP_REPO	选择用于下载 Release 的 GitHub 仓库。
GOTIFY_RMCP_RELEASE_BASE_URL	选择自定义 Release 基础 URL。

从源代码构建

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

最低支持的 Rust 版本：1.86。

快速入门

1. 配置 Gotify

为确保首次调用尽可能安全，只需设置 GOTIFY_URL：

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

使用管理或发送操作前，请先在 Gotify Web UI 中创建令牌：

export GOTIFY_CLIENT_TOKEN=Cxxxxxxxxxxxxxxxx
export GOTIFY_APP_TOKEN=Axxxxxxxxxxxxxxxx

令牌角色：

令牌	环境变量	用途
客户端令牌	GOTIFY_CLIENT_TOKEN	读取和管理操作，例如消息、应用、客户端和当前用户。
应用令牌	GOTIFY_APP_TOKEN	使用 send 发送通知。

2. 运行安全的 CLI 调用

npx -y @dinglebear/rgotify health --json

3. 启动环回 HTTP MCP

GOTIFY_MCP_HOST=127.0.0.1 npx -y @dinglebear/rgotify serve

在另一个 Shell 中：

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

4. 进行首次 MCP 调用

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

客户端配置

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

如需共享一个长期运行的服务，可通过 Labby 将 Gotify 注册为 HTTP 上游；若仅在本地使用，也可直接将其作为 stdio 运行。

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

通用 MCP JSON

{
  "command": "rgotify",
  "args": ["mcp"],
  "env": {
    "GOTIFY_URL": "https://gotify.example.com"
  }
}

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

运行时接口

接口	状态	入口点	用途
MCP stdio	支持	rgotify mcp、npx -y @dinglebear/rgotify mcp	本地子进程 MCP 客户端。
MCP HTTP	支持	rgotify serve、POST /mcp	用于本地或共享服务部署的可流式 HTTP MCP。
CLI	支持	rgotify <command>	提供可编写脚本的等效功能和调试能力。
提示词	支持	send_notification、check_status	可复用的 Agent 提示词。
资源	支持	gotify://schema/mcp-tool	gotify 工具的 JSON 架构。
REST API	未提供	不适用	Gotify 已自带 REST API。
Web UI	未提供	不适用	Gotify 已自带 Web UI。

MCP 工具参考

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

读取操作

操作	描述	必需参数	可选参数
health	Gotify 服务运行状况检查。	无	无
version	Gotify 服务版本。	无	无
me	当前经过身份验证的用户。	无	无
messages	列出消息。	无	app_id、limit、since
applications	列出应用。	无	无
clients	列出客户端。	无	无
status	返回运行时状态、配置快照和计数器。	无	无

写入操作

操作	描述	必需参数	可选参数
send	发送推送通知。	message	title、priority、extras
create_application	创建应用。	name	description、default_priority
update_application	更新应用。	app_id	name、description、default_priority
create_client	创建客户端。	name	无

破坏性操作

破坏性操作需要在 MCP 参数中设置 confirm=true、在 CLI 中使用 --confirm，或在进程环境中设置 GOTIFY_ALLOW_DESTRUCTIVE=true。

操作	描述	必需参数
delete_message	删除一条消息。	id、confirm
delete_all_messages	删除所有消息。	confirm
delete_application	删除应用及其消息。	app_id、confirm
delete_client	删除客户端。	client_id、confirm

元信息、提示词和资源

原语	名称 / URI	用途
工具操作	help	返回内置的 Markdown 工具帮助。
提示词	send_notification	引导 Agent 发送通知。
提示词	check_status	检查运行状况和近期消息。
资源	gotify://schema/mcp-tool	返回当前基于操作的 JSON 架构。

精选的操作摘要存放于此。在生成 docs/MCP_SCHEMA.md 之前，当前分支的源代码和 docs/INVENTORY.md 是完整参数的准确信息来源。

CLI 参考

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

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]

两个单词形式支持连字符别名：create-app、 update-app、create-client、delete-message、delete-all、delete-app、 delete-client。

已知的功能对等例外：action=status 是 MCP 专用的可观测性功能。用于运维检查的 CLI 对应命令是 rgotify doctor --json。

配置

如果存在 config.toml，配置会从中加载，然后由环境变量覆盖这些值。启动时，二进制文件还会在主机上加载 ~/.gotify/.env，或在容器中加载 /data/.env，且不会覆盖已设置的变量。

必需的上游变量

变量	必需	描述
GOTIFY_URL	是	Gotify 服务基础 URL，例如 https://gotify.example.com。
GOTIFY_CLIENT_TOKEN	用于管理	用于读取和管理操作的 Gotify 客户端令牌。
GOTIFY_APP_TOKEN	用于 send	仅用于发送通知的 Gotify 应用令牌。

运行时变量

变量	默认值	描述
GOTIFY_ALLOW_DESTRUCTIVE	false	跳过破坏性操作确认门槛。
GOTIFY_MCP_HOST	0.0.0.0	HTTP MCP 绑定主机。
GOTIFY_MCP_PORT	40020	HTTP MCP 绑定端口。
GOTIFY_MCP_TOKEN	empty	非回环开发模式下，HTTP MCP 使用的静态 bearer token。
GOTIFY_MCP_NO_AUTH	false	禁用 HTTP MCP 身份验证。仅用于回环地址或受信任的网关后方。
GOTIFY_MCP_AUTH_MODE	bearer	设为 oauth，通过 lab-auth 使用 Google OAuth。
GOTIFY_MCP_PUBLIC_URL	empty	用于 OAuth 元数据和受保护资源发现的公共 URL。
GOTIFY_MCP_GOOGLE_CLIENT_ID	empty	Google OAuth 客户端 ID。
GOTIFY_MCP_GOOGLE_CLIENT_SECRET	empty	Google OAuth 客户端密钥。
GOTIFY_MCP_AUTH_ADMIN_EMAIL	empty	初始/管理员 OAuth 邮箱。
GOTIFY_MCP_AUTH_SQLITE_PATH	<data>/auth.db	OAuth 状态数据库路径。
GOTIFY_MCP_AUTH_KEY_PATH	<data>/auth-jwt.pem	OAuth JWT 签名密钥路径。
GOTIFY_MCP_ALLOWED_HOSTS	empty	以逗号分隔的 Host 标头允许列表。
GOTIFY_MCP_ALLOWED_ORIGINS	empty	以逗号分隔的 Origin 标头允许列表。
GOTIFY_NOAUTH	false	允许无身份验证绑定非回环地址的应急选项。见下文。
GOTIFY_MCP_HOME	~/.gotify 或 /data	覆盖 rgotify setup 使用的 appdata 目录。
RUNNING_IN_CONTAINER	unset	强制使用 /data appdata 路径。
RUST_LOG	info	Rust 日志过滤器。Stdio 日志不得输出到 stdout。

GOTIFY_MCP 也是 lab-auth 的环境变量前缀，因此 lab-auth 还会读取此处未列出的其他 GOTIFY_MCP_* 键。

启动绑定保护

如果服务器将绑定到非回环主机且未配置身份验证，服务器将拒绝启动。若要绑定到 0.0.0.0，请设置 GOTIFY_MCP_TOKEN，或使用 GOTIFY_MCP_AUTH_MODE=oauth，或仅在上游网关确实 强制执行身份验证时设置 GOTIFY_NOAUTH=true。

身份验证

策略	适用情形	效果
回环开发	GOTIFY_MCP_HOST 以 127. 开头，或设置了 GOTIFY_MCP_NO_AUTH=true	不会挂载 HTTP 身份验证层。仅用于本地测试。
静态 bearer	已设置 GOTIFY_MCP_TOKEN，且服务器不处于回环开发模式	/mcp 需要 Authorization: Bearer <token>。
OAuth	GOTIFY_MCP_AUTH_MODE=oauth，并配置了 Google OAuth	/mcp 使用 lab-auth OAuth 和带作用域的 bearer token。
Stdio	rgotify mcp	本地子进程边界即信任边界。

MCP 作用域为 gotify:read 和 gotify:write。静态 bearer token 授予这两个作用域。OAuth token 会在分发 MCP 调用前进行检查。

安全与信任模型

• MCP 调用方不得将 Gotify 客户端 token、Gotify 应用 token、OAuth 密钥、静态 bearer token、密码或 API 密钥作为工具参数提供。
• 上游凭据仅从环境变量/配置中加载。
• 删除操作需要 confirm=true、--confirm，或显式设置进程级覆盖项 GOTIFY_ALLOW_DESTRUCTIVE=true。
• Gotify 是通知状态的持久数据来源；此服务器只是该 API 的轻量投影。
• Stdio 模式以用户的本地权限运行，并非沙箱。
• HTTP 模式不应暴露到回环地址之外，除非启用了 bearer 或 OAuth 身份验证， 并由上游反向代理提供 TLS。

架构

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

路径	用途
src/app.rs	业务服务层、破坏性操作门槛、响应整形。
src/gotify.rs	Gotify REST 客户端。
src/mcp/	RMCP 工具、提示词、资源、架构和身份验证检查。
src/cli/	CLI 解析器、doctor、setup 辅助工具和输出格式化。
src/config.rs	环境变量/配置加载和默认值。
packages/gotify-rmcp/	npm 启动器和发布二进制文件下载器。

轻量封装规则是有意为之：MCP 和 CLI 负责解析输入、调用 GotifyService 并返回输出。凭据处理、破坏性操作门槛和 Gotify API 行为都在 MCP 和 CLI 封装之外处理。

分发约定

构件	文件	必须保持一致的内容
Rust crate/二进制文件	Cargo.toml、Cargo.lock	Git 标签、发布资源、CLI 文档、安装脚本。
npm 启动器	packages/gotify-rmcp/package.json、bin/rgotify.js、lib/platform.js、scripts/install.js	GitHub Release 标签，以及名为 rgotify-x86_64.tar.gz 和 rgotify-windows-x86_64.tar.gz 的资源。
GitHub Releases	.github/workflows/*、scripts/install.sh	包版本、二进制文件名称、校验和、支持的平台。
Docker / Compose	config/Dockerfile、docker-compose*.yml	暴露端口 40020、健康检查 /health、环境文件约定。
MCP registry	server.json	服务标识 tv.nashost/gotify-rmcp、环境变量、传输 URL、包版本。
插件	plugins/gotify	运行时命令、用户配置、捆绑的元数据。不包含钩子。
文档	README.md、docs/INVENTORY.md、docs/QUICKSTART.md	当前二进制文件名称、默认端口、操作列表和环境变量名称。

发布不变量：npm 包版本、Rust crate 版本、server.json.version、 GitHub Release 标签、发布资源名称和 README 安装示例应同步更新。README 示例必须使用规范的仓库和二进制文件名称，而非旧别名。

开发

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

验证

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

如需进行实时发送或管理测试，请添加 Gotify 实例提供的 GOTIFY_CLIENT_TOKEN 和 GOTIFY_APP_TOKEN。

部署

Docker / Compose

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

容器会将应用数据存储在 /data 下，通常挂载自 ${HOME}/.gotify。

反向代理

仅暴露 /mcp 和 /health。保留 Streamable HTTP 标头，要求使用 TLS， 并在将服务暴露到本机回环地址之外之前配置 bearer 或 OAuth 身份验证。

插件

该插件不包含 Claude Code 钩子，因此不会替你运行设置。安装或更新插件后， 请手动运行一次：

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 会创建 appdata 目录和占位 .env； rgotify setup install 会在 ~/.local/bin 中保留一份可在终端中调用的副本（执行 /plugin update 后需重新运行）。rgotify setup check 会验证 appdata、.env、 PATH 中是否有二进制文件，以及端口 40020 是否空闲。服务本身会从插件的 .mcp.json ${user_config.*} 块中读取配置，因此这些命令用于初始化本地环境， 而不是配置服务。

故障排除

症状	可能原因	解决方法
/mcp 返回 401	缺少或 bearer/OAuth 令牌错误。	检查 GOTIFY_MCP_TOKEN 和客户端标头，或在本机使用回环开发模式。
CLI 健康检查失败	GOTIFY_URL 缺失或无法访问。	导出 GOTIFY_URL，并确认此主机可以访问 Gotify。
send 因身份验证错误而失败	令牌类型错误。	发送时使用 GOTIFY_APP_TOKEN，管理时使用 GOTIFY_CLIENT_TOKEN。
破坏性操作被阻止	确认门禁正在生效。	添加 confirm=true、--confirm，或有意设置 GOTIFY_ALLOW_DESTRUCTIVE=true。
stdio MCP JSON 解析错误	日志输出到了 stdout。	不要将协议日志输出到 stdout，必要时调低 RUST_LOG。
npm 启动器找不到二进制文件	发布资源下载失败或被跳过。	重新安装，检查 GOTIFY_RMCP_VERSION，或从源代码构建 rgotify。

相关服务

• soma - 为由提供方支持的 MCP 服务提供 RMCP 运行时。
• unifi-rmcp - UniFi 控制器 REST API 桥接服务。
• tailscale-rmcp - 面向设备、用户和 tailnet 操作的 Tailscale API 桥接服务。
• unraid - Unraid 单体仓库：GraphQL MCP 桥接服务（runraid）和 Unraid 插件。
• apprise-rmcp - Apprise 通知分发桥接服务，支持多种投递后端。
• arcane-rmcp - 用于管理容器及相关资源的 Arcane Docker 管理桥接服务。
• yarr - 面向 Sonarr、Radarr、Prowlarr、Plex 及相关服务的媒体栈桥接服务。
• ytdl-rmcp - 媒体下载和元数据工作流服务。
• synapse-rmcp - 用于侦察和 flux 操作的本地 Synapse 工作流服务。
• cortex - Syslog 和家庭实验室日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - 家庭实验室控制平面和 MCP 网关项目。
• lumen - 本地语义代码搜索 MCP 服务。

文档

从这里开始：

• docs/QUICKSTART.md - 精简的设置流程。
• docs/INVENTORY.md - 操作、CLI 命令、环境变量和端点的组件清单。
• docs/RUST.md - Rust 开发说明。
• docs/stack/ARCH.md - 技术栈架构详情。
• server.json - MCP 注册表元数据。
• packages/gotify-rmcp/README.md - npm 软件包启动器说明。

本 README 经过精心编排。生成的目录或详尽目录应在各自的文件中更新，并作为当前分支详情的事实来源。

许可证

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