mcp-uptime-kuma

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](# 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

| 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. |
| pauseMonitor | Pause a monitor to stop performing checks. |
| resumeMonitor | Resume a paused monitor to restart checks. |
| listHeartbeats | Get status check history for all monitors. |
| getHeartbeats | Get status check history for a specific monitor. |
| 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)

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

# 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:

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

# 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