gotify-mcp (Gotify MCP connector)

MCP connector for a self-hosted Gotify server (v3.1.1 API). It speaks the Gotify REST API over stdio and over stateless Streamable HTTP on localhost.

Gotify server is MIT. This connector is a local client. It is not affiliated with the Gotify project. A call does not transfer trademarks or a right to say that Gotify endorses this project.

The registry covers 38 of the 42 operations in gotify.openapi.json. Four operations are excluded because they are not request/response calls. scripts/gen-operations.mjs holds that allow-list, and test/operations.test.ts repeats it.

There is no hosted Gotify to refuse. GOTIFY_URL is required. Set it to the origin of your server, for example http://127.0.0.1:8090. The value must be http or https, with no username, password, query, or hash.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication. Keep it on localhost.

Create a client in the Gotify UI and copy its token into GOTIFY_TOKEN. Create an application and copy its token into GOTIFY_APP_TOKEN when you want to send messages. The connector sends either token as X-Gotify-Key and never prints the value.

{
  "mcpServers": {
    "gotify": {
      "command": "node",
      "args": ["/workspace/connectors/gotify/dist/index.js"],
      "env": {
        "GOTIFY_URL": "http://127.0.0.1:8090",
        "GOTIFY_TOKEN": "...",
        "GOTIFY_APP_TOKEN": "...",
        "GOTIFY_ALLOW_WRITES": "false",
        "GOTIFY_TOOLSETS": "info,messages,applications",
        "GOTIFY_CONTACT": "you@example.com"
      }
    }
  }
}

Docker (HTTP, no authentication, localhost only):

docker build -t gotify .
docker run -p 3000:3000 \
  -e GOTIFY_URL=http://host.docker.internal:8090 \
  -e GOTIFY_TOKEN=... \
  gotify

Do not put tokens in the image.

Regenerate the operations registry after a spec bump:

npm run gen:operations

Related MCP server: agent-notify

Config

Invalid values are reported by field name and issue code. The rejected value is not included.

When both GOTIFY_TOKEN and basic auth are set, client calls send the token.

Safety

Every non-GET is a write. A write needs confirm set to the boolean true and GOTIFY_ALLOW_WRITES=true. Otherwise the tool returns a dry-run preview of the method, path, query, redacted body, content type, and which credential would be sent. The preview does not send the request. The string "true" is rejected.

These operations add an extra warning in the preview and in the tool description. Deletes of a message, of every message, of one application's messages, of an application, of a client, and of a user. Creates that mint a credential (application, client, user, local login, OIDC token exchange). Client elevation. Application security changes. Password changes. Plugin enable, disable, and config replacement. Logout, which invalidates the token in use.

create_message is a write because it pushes a notification. It does not add the extra warning. It refuses to run unless GOTIFY_APP_TOKEN is set. The preview names that variable and never the token value. priority must be an integer from -128 to 128.

POST /application/{id}/image takes {filename, content_base64} and sends multipart field file. Decoded size is capped at 2 MB. POST /plugin/{id}/config takes a YAML string and sends application/x-yaml. local_login takes {name, username, password}. Gotify receives form field name plus HTTP basic auth. The password is redacted.

Application, client, and plugin token fields are redacted on list, get, update, and preview. A confirmed create_application, create_client, local_login, or oidc_external_token returns the new token once, with the note token shown only once. The caller's own tokens and password are always redacted. message and title are user data and stay in the output, truncated at 4096 characters.

Responses are capped at 1 MB. Errors use a fixed set of codes. 401 unauthorized, 403 forbidden, 404 not-found, 400, 409, and 422 invalid, 429 rate-limit with Retry-After, 5xx server, network, and timeout. Stack traces and filesystem paths are removed.

Tools

Default GOTIFY_TOOLSETS publishes 3 tools (17 operations). GOTIFY_TOOLSETS=all publishes 7 tools (38 operations). Each tool takes action plus params, query, body, and confirm on writes.

Excluded operations:

Example. Read health, preview a message, then send it:

{ "action": "get_health" }

{ "action": "create_message", "body": { "message": "backup finished", "title": "Backup", "priority": 2 } }

{ "action": "create_message", "body": { "message": "backup finished", "title": "Backup", "priority": 2 }, "confirm": true }

The first call uses gotify_info. The other two use gotify_messages.

What this is not

This is not a Gotify WebSocket client, a browser OIDC login, or a hosted multi-tenant service. There is no default URL. It does not store tokens on disk. scripts/live-check.mjs is the parent live check against a local Gotify. This session did not run that script. See LIVE-CHECK.md.

Limits

• In-memory TTL cache (GOTIFY_CACHE_TTL_SEC, default 60 seconds). A cache hit does not spend the local rate limit. The cache is dropped when the process exits. Writes clear it.

• Local sliding window (GOTIFY_PER_MINUTE, default 30 requests per 60 seconds) around upstream calls.

• When the local window is full, the tool returns isError with a [rate-limit] message and a retry hint.

Elevated sessions (Gotify 3)

Gotify 3 requires an elevated session for user management, deleting or changing applications and clients, and token security changes. A plain client token is not elevated and gets a 403 "session not elevated". Use GOTIFY_USER and GOTIFY_PASSWORD (basic auth is always elevated), or elevate the client once with basic auth through the clients toolset elevate_client action. The connector adds a hint to that 403 error.

License

MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Gotify project or its owners.

gotify.openapi.json is from gotify/server (MIT, Copyright (c) 2018 jmattheis).