mcp-uptime-kuma

This is a fork of DavidFuchs/mcp-uptime-kuma. For the original project please refer to the upstream repository. This fork is published under @burg_dal/mcp-uptime-kuma and contains the following changes not yet merged upstream:

• important filter for getHeartbeats / listHeartbeats — filters results to status-change events only (UP↔DOWN transitions), making outage analysis practical within the 100-entry cache window
• HeartbeatSchema.passthrough() — preserves unknown fields from the Uptime Kuma API instead of silently dropping them

A Model Context Protocol (MCP) server for Uptime Kuma version 2. Supports stdio and streamable HTTP transports.

Features

• Real-time Monitoring: Access monitors, heartbeats, uptime, and responsiveness metrics via Socket.IO with instant status change notifications.
• Context-Friendly: Returns only essential data by default to avoid overwhelming LLM context windows.
• Multiple Transports: Supports stdio (local) and streamable HTTP (remote) transports.

Quick Start

Using npx (stdio transport)

Add this to your MCP client configuration:

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "npx",
      "args": ["-y", "@davidfuchs/mcp-uptime-kuma"],
      "env": {
        "UPTIME_KUMA_URL": "http://your-uptime-kuma-instance:3001",
        "UPTIME_KUMA_USERNAME": "your_username",
        "UPTIME_KUMA_PASSWORD": "your_password"
      }
    }
  }
}

Using Docker (streamable HTTP transport)

Option 1: Docker Run

docker run -d \
  --name mcp-uptime-kuma \
  -p 3000:3000 \
  -e UPTIME_KUMA_URL=http://your-uptime-kuma-instance:3001 \
  -e UPTIME_KUMA_USERNAME=your_username \
  -e UPTIME_KUMA_PASSWORD=your_password \
  davidfuchs/mcp-uptime-kuma:latest \
  -t streamable-http

Option 2: Docker Compose

A docker-compose.yml file is provided in the repository. Download it, configure your environment variables, and run:

docker compose up -d

Then configure your MCP client to connect to the endpoint:

{
  "mcpServers": {
    "uptime-kuma": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

See Authentication Methods for JWT token and anonymous authentication options.

Example Conversation

Conversation in LibreChat where the mcp-uptime-kuma server is providing real-time information from Uptime Kuma.

Available Tools

Monitors

| Tool | Purpose | |------|---------| | getMonitorSummary | Get a quick overview of all monitors with their current status. Supports filtering. | | listMonitors | Get the full list of all monitors with configurations. Supports filtering. | | listMonitorTypes | Get all available monitor types supported by Uptime Kuma. | | getMonitor | Get detailed configuration for a specific monitor by ID. | | createMonitor | Create a new monitor (requires name and type at minimum). | | updateMonitor | Update an existing monitor's configuration. | | deleteMonitor | Permanently delete a monitor and all its heartbeat history. | | pauseMonitor | Pause a monitor to stop performing checks. | | resumeMonitor | Resume a paused monitor to restart checks. |

Heartbeats

| Tool | Purpose | |------|---------| | listHeartbeats | Get status check history for all monitors. | | getHeartbeats | Get status check history for a specific monitor. |

Both heartbeat tools support filtering by:

• maxHeartbeats: Number of heartbeats to return per monitor (up to 100)
• important: true = only status-change events (UP↔DOWN transitions), false = only non-status-change heartbeats

Examples:

getHeartbeats({ monitorID: 5, maxHeartbeats: 100, important: true })  // All status changes for monitor 5
listHeartbeats({ maxHeartbeats: 100, important: true })                // Status changes across all monitors

Note: The cache holds the last 100 heartbeats per monitor (Uptime Kuma's server limit). Using important: true is especially useful for outage analysis since status-change events are infrequent and cover a longer time window within that cache.

Notifications

| Tool | Purpose | |------|---------| | listNotifications | List all configured notification channels (Slack, Discord, email, webhooks, etc.). | | addNotification | Create a new notification channel. | | updateNotification | Update an existing notification channel. | | deleteNotification | Permanently delete a notification channel. |

Tags

| Tool | Purpose | |------|---------| | listTags | List all tags defined in Uptime Kuma. | | addTag | Create a new tag that can be assigned to monitors. | | deleteTag | Permanently delete a tag (removes it from all monitors). |

Maintenance

| Tool | Purpose | |------|---------| | getMaintenanceWindows | List all scheduled maintenance windows. | | createMaintenance | Schedule a new maintenance window. |

Status Pages & Settings

| Tool | Purpose | |------|---------| | listStatusPages | List all configured status pages. | | getSettings | Get Uptime Kuma server settings. |

Filtering

getMonitorSummary and listMonitors support filtering by:

• keywords: Space-separated keywords for fuzzy matching against monitor pathNames
• type: Monitor type(s), comma-separated (e.g., "http", "http,ping,dns")
• active: Filter by active (true) or inactive (false) monitors
• maintenance: Filter by maintenance mode status
• tags: Tag name and optional value, comma-separated (e.g., "production", "env=staging")
• status (getMonitorSummary only): Heartbeat status ("0"=DOWN, "1"=UP, "2"=PENDING, "3"=MAINTENANCE)

getHeartbeats and listHeartbeats support filtering by:

• important: true = only status-change events (UP↔DOWN transitions), false = only non-status-change heartbeats

Examples:

getMonitorSummary({ status: "0" })                                     // All DOWN monitors
getMonitorSummary({ type: "http", maintenance: true })                 // HTTP monitors in maintenance
listMonitors({ tags: "production,region=us-east" })                    // Monitors with specific tags
getHeartbeats({ monitorID: 5, maxHeartbeats: 100, important: true })  // Status changes for monitor 5
listHeartbeats({ maxHeartbeats: 100, important: true })                // Status changes across all monitors

Authentication Methods

Anonymous Authentication

If authentication is disabled on your Uptime Kuma instance, only UPTIME_KUMA_URL is required.

Username/Password Authentication

UPTIME_KUMA_URL=http://your-instance:3001
UPTIME_KUMA_USERNAME=your_username
UPTIME_KUMA_PASSWORD=your_password
UPTIME_KUMA_2FA_TOKEN=123456  # Optional, only if 2FA is enabled

JWT Token Authentication

Recommended for 2FA users. Takes precedence over username/password if both are provided.

UPTIME_KUMA_URL=http://your-instance:3001
UPTIME_KUMA_JWT_TOKEN=your_jwt_token

Obtaining Your JWT Token

Using the CLI utility (recommended):

npx -p @davidfuchs/mcp-uptime-kuma mcp-uptime-kuma-get-jwt http://localhost:3001 admin mypassword

Using Docker:

docker run --rm davidfuchs/mcp-uptime-kuma:latest get-jwt http://host.docker.internal:3001 admin mypassword

From browser: Open Developer Tools → Storage/Application → Local Storage → find token key.

LibreChat Configuration

stdio transport:

mcpServers:
  uptime-kuma:
    command: npx
    args: ["-y", "@davidfuchs/mcp-uptime-kuma"]
    env:
      UPTIME_KUMA_URL: "http://your-instance:3001"
      UPTIME_KUMA_USERNAME: "your_username"
      UPTIME_KUMA_PASSWORD: "your_password"
    serverInstructions: true

streamable HTTP transport:

Update the allowed domains to whatever domain you're using in the URL (e.g., localhost or host.docker.internal for Docker setups):

mcpServers:
  uptime-kuma:
    type: streamable-http
    url: "http://mcp-uptime-kuma:3000/mcp"
    serverInstructions: true

mcpSettings:
  allowedDomains:
    - 'mcp-uptime-kuma'

Contributing

For development setup, building, testing, and project structure, see CONTRIBUTING.md.

Learn More

• Uptime Kuma
• Model Context Protocol Documentation
• MCP TypeScript SDK
• MCP Specification