MCP Uptime Kuma

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@latest"], "env": { "UPTIME_KUMA_URL": "http://your-uptime-kuma-instance:3001", "UPTIME_KUMA_USERNAME": "your_username", "UPTIME_KUMA_PASSWORD": "your_password" } } } }

Keep the @latest suffix. Without it, npx reuses whatever version it cached the first time it ran and never picks up new releases.

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.

The endpoint above is unauthenticated. Anyone who can reach port 3000 gets full

read/write control of your Uptime Kuma instance. See

Securing the HTTP Endpoint before exposing it beyond localhost.

Example Conversation

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

Available Tools

Monitors

Heartbeats

Notifications

Tags

Maintenance

Status Pages & 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")
• parentId: Group monitor ID, returning that group's direct children. Pass null for top-level monitors (those with no parent). Not recursive — to walk deeper, use each child group's own childrenIDs.
• 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 getMonitorSummary({ parentId: 12, status: "0" }) // What's down inside group 12 listMonitors({ tags: "production,region=us-east" }) // Monitors with specific tags listMonitors({ parentId: 12 }) // Direct children of group 12 listMonitors({ parentId: null }) // Top-level monitors only

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@latest 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.

Behind an Authenticating Proxy (Cloudflare Access, etc.)

If Uptime Kuma sits behind a proxy that demands its own credentials — a Cloudflare Zero Trust Access application, oauth2-proxy, an API gateway — set UPTIME_KUMA_HEADERS to a JSON object of headers to send on every request. It combines with any of the methods above, which still handle logging in to Uptime Kuma itself.

For Cloudflare Access, create a service token, add a *Service Auth* policy to the application that allows it, then:

UPTIME_KUMA_URL=https://uptime.example.com

UPTIME_KUMA_HEADERS={"CF-Access-Client-Id":" .access","CF-Access-Client-Secret":" "} UPTIME_KUMA_USERNAME=your_username UPTIME_KUMA_PASSWORD=your_password

In an MCP client's JSON config the value is a string, so the inner quotes need escaping:

"UPTIME_KUMA_HEADERS": "{\"CF-Access-Client-Id\":\"<client-id>.access\",\"CF-Access-Client-Secret\":\"<client-secret>\"}"

mcp-uptime-kuma-get-jwt reads the same variable. A malformed value stops the server at startup with an error naming the offending header; header values are never logged.

Securing the HTTP Endpoint

Applies to -t streamable-http only. The stdio transport has no listener to protect and takes its credentials from the environment, as the MCP specification prescribes.

Anyone who can reach /mcp has full read/write control of your Uptime Kuma instance, including deleting monitors. Two settings guard it, and both default to permissive so that upgrading cannot break an existing deployment - the server warns at startup in that state.

/health is deliberately left unauthenticated so container healthchecks and load balancer probes keep working. It reports nothing but liveness.

Setting a token

Generate a high-entropy secret - this is a password, and it is compared in constant time, so length is the only thing protecting it:

openssl rand -base64 32

docker run -d \

--name mcp-uptime-kuma \ -p 3000:3000 \ -e UPTIME_KUMA_URL=http://your-uptime-kuma-instance:3001 \ -e UPTIME_KUMA_JWT_TOKEN=your_jwt_token \ -e MCP_AUTH_TOKEN=your_generated_secret \ davidfuchs/mcp-uptime-kuma:latest \ -t streamable-http

Clients then send it as a header:

{

"mcpServers": { "uptime-kuma": { "url": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer your_generated_secret" } } } }

Why Origin validation matters separately

A shared secret stops anyone who cannot present it. It does not stop a website your browser already trusts. Under a DNS rebinding attack a page on evil.example resolves its own hostname