# Gotify MCP

> Gotify MCP connects your self-hosted push notification server to any AI agent. Use it to send high-priority system alerts, delete old messages, and manage all application and client tokens using natural language commands.

## Overview
- **Category:** communication-messaging
- **Price:** Free
- **Tags:** push-notifications, self-hosted, alerts, messaging-api, server-management

## Description

This MCP lets you interact with your Gotify instance like a command line tool, but through conversation. Forget logging into the web UI or manually hitting API endpoints every time you need an alert. You can ask your AI agent to monitor your system health and push immediate notifications when something goes wrong. Need to organize your alerts? The agent handles listing all applications so you know exactly what token belongs where. Want to clean up old messages? Just tell it to delete them.

If you're building complex workflows, Vinkius makes connecting this alert hub simple. You just subscribe once and give your AI client permission to manage the underlying structure—users, clients, apps—all from a single conversation.

## Tools

### change_password
Resets the password for the currently authenticated user.

### create_application
Registers a new source (application) that is allowed to send messages through Gotify.

### create_client
Generates and registers a new client token for a specific device or service.

### create_user
Adds a new administrator user to the Gotify instance (admin only).

### delete_all_messages
Wipes out every message associated with the current client token.

### delete_application
Removes an existing notification source application from the system.

### delete_client
Deactivates a specific device or service client token.

### delete_message
Removes one specific message record by its unique ID.

### get_applications
Lists all currently registered applications and their details.

### get_clients
Retrieves a list of all active or inactive client tokens.

### get_current_user
Fetches the details and profile information for the authenticated user.

### get_health
Checks the overall operational status of the Gotify server instance.

### get_messages
Retrieves a list of historical messages associated with the current client token.

### get_plugin_config
Retrieves configuration details for any installed plugins on the server.

### get_plugin_display
Gets display information used by Gotify's internal plugin system.

### get_plugins
Lists all plugins currently installed and active on the server.

### get_users
Retrieves a list of every user account registered to the Gotify instance (admin only).

### get_version
Returns the current software version information for the server.

### send_message
Sends a new message payload to all connected clients, using an application token.

### update_application
Modifies details or settings of an existing notification source application.

### update_client
Updates the credentials or metadata for a specific client token.

### update_plugin_config
Modifies the configuration settings of an installed plugin.

## Prompt Examples

**Prompt:** 
```
Send a high-priority Gotify message titled 'System Alert' saying 'Disk space is low on Server A'.
```

**Response:** 
```
I've sent the high-priority message (Priority 8) to your Gotify server. The message 'Disk space is low on Server A' has been pushed successfully.
```

**Prompt:** 
```
List all my current Gotify applications and their descriptions.
```

**Response:** 
```
I found 3 applications: 'Backup-Bot' (Status alerts), 'GitHub-Webhooks' (Repo updates), and 'Home-Monitor' (IoT sensors). Which one would you like to manage?
```

**Prompt:** 
```
Get the last 5 messages from my Gotify server.
```

**Response:** 
```
Retrieving your recent messages... I've found 5 messages. The most recent is 'Build Success' from 10 minutes ago. Would you like me to summarize the others?
```

## Capabilities

### Send high-priority alerts
Push specific messages with custom titles and priorities out to all connected devices.

### Manage notification sources
Create, list, or remove the applications that authorize which services can send notifications.

### Control user access
Perform administrative tasks like creating users and changing passwords for your Gotify instance.

### Audit message history
Retrieve or delete specific messages from the notification stream to keep logs clean.

## Use Cases

### CI/CD Pipeline Failure Alert
A developer pushes code, and the test suite fails at 3 a.m. Instead of waiting for an email or checking a dashboard, they prompt their agent: 'Send a critical alert to Gotify saying Build #45 failed on Server Beta.' The agent uses `send_message` immediately.

### Onboarding New Services
A team needs a new microservice (Service Gamma) to send alerts. Instead of writing code to manage tokens, the admin asks the agent to 'Create and register a client for Service Gamma,' using `create_client` and getting the token right away.

### Security Audit Cleanup
The security team needs to check if any old services are still sending messages. They ask the agent to list all registered apps (`get_applications`) and then delete specific, expired tokens using `delete_client`.

### Debugging Message Delivery
A client reports that yesterday's alerts aren't visible. The developer asks the agent to retrieve messages from the last 24 hours (`get_messages`), quickly confirming if the payloads were sent and when.

## Benefits

- Stop manually checking logs. You can ask the agent to send a high-priority alert, like notifying you immediately when your build fails, without ever leaving your chat window or terminal. Just tell it what to push.
- Manage all notification resources easily. Use tools like `get_applications` and `create_application` to keep track of every service that needs access, knowing exactly which tokens are live and who owns them.
- Maintain a clean slate. If you need to clear out old, noisy messages from the stream, the agent handles it with one command, allowing you to use tools like `delete_all_messages` before running diagnostics.
- Control user access immediately. Need to onboard a new team member or restrict an old service? You can run admin tasks like `create_user` or `change_password`, ensuring your system's security posture stays locked down.
- Debug message flow instantly. If a notification isn't showing up, you can use the agent to get historical data via `get_messages` and check which apps are registered using `get_applications`—all in one conversation.

## How It Works

The bottom line is, you tell the AI what needs to be done with your alerts, and it handles all the technical connection details for you.

1. Subscribe to this MCP and enter your Gotify URL, along with the necessary Application or Client tokens.
2. Your AI agent authenticates against the server using these credentials. It verifies your permissions (e.g., admin rights vs. read-only access).
3. You issue a command—like 'Send an alert about database failure'—and the agent executes the specific API call to push the message.

## Frequently Asked Questions

**How do I send an alert using the Gotify MCP?**
You use `send_message`. Just tell your agent the title and body of the message, and it pushes the notification out immediately. You'll need a valid application token for this.

**What if I need to list all my existing apps? Do I use get_applications?**
Yes, you use `get_applications`. It runs through and lists every single notification source registered on your Gotify server. This is helpful when auditing system access.

**Can I delete messages using the Gotify MCP? Which tool should I use?**
You use `delete_message` for a specific message or `delete_all_messages` to wipe out everything. Be careful with `delete_all_messages`; it's irreversible.

**I need to change a user password; is that done through the Gotify MCP?**
Yep, you use `change_password`. This tool lets you reset passwords for users on your instance. You must have admin privileges for this.

**I need to modify an existing notification source's details; should I use the `update_application` tool?**
Yep, you use `update_application`. This lets you change descriptions or other details for a specific application without having to delete and recreate it. It’s perfect for maintenance.

**Before running alerts, how can I check if my Gotify server is actually operational? Should I use the `get_health` tool?**
Run `get_health`. This verifies the API status of your self-hosted instance. It confirms general connectivity and operational readiness before you try sending messages or managing other resources.

**How do I see a list of all registered devices or tokens connected to my system? Is there a tool for that?**
You need the `get_clients` tool. This function retrieves details for every client registered on your instance, letting you audit which services are authorized to receive messages.

**If I'm an admin and need to see all user accounts on the system, what do I use? Should I call `get_users`?**
Call `get_users`. This is an admin-only tool that lists every registered user account. It helps you manage who has access beyond just viewing applications or clients.

**How do I send a notification to my phone using this server?**
Use the `send_message` tool. You'll need to provide a message and a title. Ensure you have configured your `GOTIFY_APP_TOKEN` so the server knows which application is sending the alert.

**Can I clear all messages from my Gotify stream at once?**
Yes, you can use the `delete_all_messages` tool. This requires a valid `GOTIFY_CLIENT_TOKEN` to authorize the deletion of messages for that specific client.

**Is it possible to create new application tokens via AI?**
Absolutely. Use the `create_application` tool with a name and optional description. The AI will return the details of the new application, including its token.