pushnote

pushnote

pushnote talks to a Gotify server: it sends push notifications, reads back messages, server health and version, and manages the Gotify applications and clients that notifications flow through. Everything is exposed as one action-router tool, gotify, over a command-line interface and a stdio MCP server, both served by the same binary.

Three environment variables configure it. GOTIFY_URL is the base URL of your Gotify server and is required — without it, every action except the local help fails before any request is made. GOTIFY_CLIENT_TOKEN is a Gotify client token used for reads and management (current user, messages, applications, clients). GOTIFY_APP_TOKEN is a Gotify application token used only by the send action. Tokens come from the environment only; they are never tool arguments.

Install

npx @reneturcios/pushnote health

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/pushnote

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

Each command mirrors one router action. Multi-word commands accept both the hyphenated form shown here and the underscore action name (for example create-application or create_application).

export GOTIFY_URL=https://gotify.example.com
export GOTIFY_CLIENT_TOKEN=<client token>
export GOTIFY_APP_TOKEN=<app token>

pushnote health
pushnote version
pushnote me
pushnote messages --limit 25 --since 40
pushnote messages --app-id 7
pushnote applications
pushnote clients
pushnote status
pushnote send "deploy finished" --title CI --priority 5
pushnote create-application alerts --description "Alert channel" --default-priority 4
pushnote update-application 3 --name renamed
pushnote create-client phone
pushnote delete-message 9 --confirm
pushnote delete-all-messages --confirm
pushnote delete-application 4 --confirm
pushnote delete-client 5 --confirm
pushnote help

pushnote --version

Successful commands print the upstream JSON payload (status and help print local output instead). Exit codes: 0 on success, 1 when a call fails (including an upstream API error or a refused destructive action), 2 for usage errors.

Destructive commands — the four delete-* commands — do nothing unless --confirm is passed. Without it they fail before any request reaches the Gotify server.

MCP server

The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/pushnote mcp

MCP client configuration:

{
  "mcpServers": {
    "pushnote": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pushnote", "mcp"],
      "env": {
        "GOTIFY_URL": "https://gotify.example.com",
        "GOTIFY_CLIENT_TOKEN": "<client token>",
        "GOTIFY_APP_TOKEN": "<app token>"
      }
    }
  }
}

Tool

One tool, gotify, takes a required action argument plus the parameters that action needs as optional top-level arguments:

Action	Required	Optional	Token
health	—	—	none
version	—	—	none
me	—	—	client
messages	—	app_id, limit, since	client
applications	—	—	client
clients	—	—	client
status	—	—	none (local)
send	message	title, priority, extras	app
create_application	name	description, default_priority	client
update_application	app_id	name, description, default_priority	client
create_client	name	—	client
delete_message	id, confirm	—	client
delete_all_messages	confirm	—	client
delete_application	app_id, confirm	—	client
delete_client	client_id, confirm	—	client
help	—	—	none (local)

All four delete actions refuse to run unless confirm is true, and that check happens before any request. status returns a local snapshot (Gotify URL, which tokens are configured, action count) and never includes a token value. help returns the action documentation locally.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.