Skip to main content
Glama
uptime-kuma-mcp-server

uptime-kuma-mcp-server

by mehbul

Uptime Kuma MCP server

Connect an MCP client to an existing Uptime Kuma instance to inspect monitors, review checks, manage monitors, and read Prometheus metrics. This is an independent community integration; it is not an official Uptime Kuma component.

Requirements and verification

Use Node.js 22 or newer. All 12 tools were exercised over both stdio and authenticated HTTP through an MCP client against a disposable Uptime Kuma 2.5.7 instance on Windows with Node.js 24.15.0. See validation and the demo. HTTP, keyword, TCP port, ping, DNS and push monitor lifecycles are live-tested. Steam, MQTT and Docker creation is not exposed; configure those in Kuma directly. Other Kuma versions need additional testing.

npm ci
npm test

Related MCP server: UptimeRobot MCP Server

Connect over stdio

Build with npm run build, then add this configuration to your MCP client. Replace the path and credentials with your own values:

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "node",
      "args": ["/absolute/path/to/uptime-kuma-mcp-server/dist/index.js"],
      "env": {
        "UPTIME_KUMA_URL": "http://127.0.0.1:3001",
        "UPTIME_KUMA_USERNAME": "your-username",
        "UPTIME_KUMA_PASSWORD": "your-password"
      }
    }
  }
}

Alternatively set UPTIME_KUMA_TOKEN to a Kuma login JWT. UPTIME_KUMA_API_KEY is only for /metrics; it does not authenticate Socket.IO tools. Username/password login supports UPTIME_KUMA_TOTP when a fresh two-factor code is required. The first successful password/TOTP login caches its returned JWT in memory for later calls. A fresh process needs a new code or an explicit login JWT. Reusing a one-time code for another password login will not work.

Local Streamable HTTP

HTTP mode requires a separate MCP_HTTP_TOKEN. It binds to 127.0.0.1 and accepts non-browser clients with Authorization: Bearer <MCP_HTTP_TOKEN>. It rejects browser Origin headers and unexpected Host headers. It is not a public hosting configuration.

PowerShell:

$env:UPTIME_KUMA_URL = 'http://127.0.0.1:3001'
$env:UPTIME_KUMA_USERNAME = 'your-username'
$env:UPTIME_KUMA_PASSWORD = 'your-password'
$env:MCP_HTTP_TOKEN = 'replace-with-a-long-random-token'
$env:TRANSPORT = 'http'
$env:PORT = '3000'
node dist/index.js

Point your MCP client to http://127.0.0.1:3000/mcp with that bearer header. /health is an unauthenticated liveness endpoint; it does not check Kuma connectivity. Concurrent requests use independent MCP server instances.

Tools

Tool prefix: uptime_kuma_

Behavior

list_monitors

Search and paginate monitor configuration

get_monitor

Read one monitor without credential fields

create_monitor

Create an HTTP, keyword, port, ping, DNS or push monitor

edit_monitor

Merge provided fields; active changes invoke Kuma pause/resume

delete_monitor

Delete a monitor and its history

pause_monitor / resume_monitor

Stop/start monitoring

get_heartbeats

Recent checks, newest first

get_status

Successful-check ratio and weighted average ping from Kuma chart buckets

list_notifications

Channel ID, name, type and active state; credentials omitted

list_status_pages

Status-page configuration

get_metrics

Prometheus exposition from authenticated /metrics

list_monitors supports limit, offset, and search. Read tools with a response_format parameter accept markdown or json. An API failure returns isError: true; status with no observations returns null instead of inventing 0% uptime. Status comes from Kuma's aggregate chart buckets, not a separately calculated wall-clock SLA.

Creating a push monitor returns its secret push_url; keep that URL private. DNS creation accepts dns_resolve_type, dns_resolve_server, and an optional resolver port.

Monitor credential fields are filtered, but names, URLs, descriptions, heartbeats and metrics can still contain private operational information. Only connect clients you trust. Write tools use your Kuma account's permissions; tool annotations do not enforce user approval.

Development

npm test

To reproduce the live demo, install a separate Kuma 2.5.7 source checkout with npm ci --omit=dev. Then:

$env:KUMA_TEST_SERVER_DIR = 'C:\path\to\uptime-kuma-2.5.7'
npm run test:live

The runner uses an ephemeral loopback port and a new temporary SQLite data directory, creates its own demo account, runs the tools, and stops the server. It does not connect to an existing deployment. Temporary test data is retained under the system temp directory for diagnosis.

See contributing for upstream discussion and review requirements.

License

MIT. See LICENSE.

Available Tools

12 tools
uptime_kuma_create_monitorCreate Uptime Kuma MonitorA

Create a new monitor. Returns new monitorID.

Args:

  • name (required): display name

  • type: http|port|ping|keyword|dns|push|steam|mqtt|docker (default http)

  • url/hostname/port/keyword as required by type

  • interval (default 60, min 20)

  • notificationIDList (optional): { "1": true }

Use when: "monitor https://example.com every 60s" Don't use for edits (use edit_monitor).

Inputs: name (required), url, port, type, +7 more.

uptime_kuma_delete_monitorDelete Uptime Kuma MonitorA
DestructiveIdempotent

Delete a monitor and its heartbeat history (destructive).

Args:

  • monitor_id (int)

Requires confirmation — this is irreversible.

Inputs: monitor_id (required).

uptime_kuma_edit_monitorEdit Uptime Kuma MonitorA
Idempotent

Edit existing monitor. Only provided fields are updated.

Args:

  • id (required): monitor ID

  • name, url, interval, active, description (optional)

Use when: renaming, changing URL/interval.

Inputs: id (required), url, name, active, +2 more.

uptime_kuma_get_heartbeatsGet Uptime Kuma HeartbeatsA
Read-onlyIdempotent

Get recent heartbeats for a monitor (status, ping, msg, time).

Args:

  • monitor_id

  • period_hours (1-720, default 24)

  • limit (1-200, default 50)

  • response_format

Returns newest-first list. Use when: "show recent checks for monitor 5", "why was it down?"

Inputs: monitor_id (required), limit, period_hours, response_format.

uptime_kuma_get_metricsGet Uptime Kuma Prometheus MetricsA
Read-onlyIdempotent

Fetch Prometheus metrics from /metrics (requires UPTIME_KUMA_API_KEY or username/password).

Returns raw Prometheus exposition format. Useful for AI to parse monitor_status, monitor_response_time.

No params.

Inputs: no named parameters.

uptime_kuma_get_monitorGet Uptime Kuma MonitorA
Read-onlyIdempotent

Get single monitor details by ID.

Args:

  • monitor_id (int): ID from list_monitors

  • response_format: markdown or json

Returns all fields (type, url, interval, status, tags). Use when: need edit/delete/pause context.

Inputs: monitor_id (required), response_format.

uptime_kuma_get_statusGet Uptime Kuma Monitor StatusA
Read-onlyIdempotent

Get uptime ratio and avg ping for a monitor over a period.

Args:

  • monitor_id

  • period_hours (default 24)

  • response_format

Returns: uptime (0-1), avgPing ms, computed from heartbeats if needed.

Inputs: monitor_id (required), period_hours, response_format.

uptime_kuma_list_monitorsList Uptime Kuma MonitorsA
Read-onlyIdempotent

List monitors from Uptime Kuma with pagination and optional search.

Args:

  • limit (1-100, default 20): max to return

  • offset (default 0): skip N for pagination

  • search (optional): filter name/type substring

  • response_format: markdown (default) or json

Returns paginated list with has_more/next_offset. Use when: "show my monitors", "list http monitors", "what do I monitor?" Don't use when: you need single monitor details (use uptime_kuma_get_monitor).

Inputs: limit, offset, search, response_format.

uptime_kuma_list_notificationsList Uptime Kuma NotificationsA
Read-onlyIdempotent

List notification channels (Slack, email, Telegram, etc.) configured in Uptime Kuma.

Returns id/name/type/active. Use when wiring monitor to notification.

Inputs: response_format.

uptime_kuma_list_status_pagesList Uptime Kuma Status PagesA
Read-onlyIdempotent

List public status pages.

Returns id/slug/title/published.

Inputs: response_format.

uptime_kuma_pause_monitorPause Uptime Kuma MonitorA
Idempotent

Pause heartbeat checks for a monitor (sets active=false).

Args: monitor_id

Inputs: monitor_id (required).

uptime_kuma_resume_monitorResume Uptime Kuma MonitorA
Idempotent

Resume a paused monitor.

Args: monitor_id

Inputs: monitor_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct resource/action: monitors are separated into list/get/create/edit/delete/pause/resume, while health data is split into heartbeats, status, and metrics. Notifications and status pages are clearly separate read-only listing tools, so there is little risk of misselection.

    Naming Consistency5/5

    All tools follow the same uptime_kuma_ prefix with a consistent verb_noun structure in snake_case: list_monitors, get_monitor, create_monitor, edit_monitor, delete_monitor, pause_monitor, resume_monitor. The naming pattern is uniform and predictable.

    Tool Count5/5

    Twelve tools is well-scoped for an Uptime Kuma server, covering monitor lifecycle, operational controls, health data, notifications, status pages, and metrics. Each tool fills a distinct role with no obvious redundancy.

    Completeness4/5

    Monitor CRUD, pause/resume, heartbeats, uptime status, and metrics provide strong lifecycle coverage for core monitoring workflows. The main gap is that notifications and status pages only have list operations, with no create/update/delete tools, though this is workable for read-oriented usage.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables users to manage OmniWatchGuard website monitors and alerts via natural language. Supports listing, creating, updating, pausing, resuming, and deleting monitors, plus reviewing recent notifications across channels.
      7
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM clients to manage Uptime Kuma HTTP(S) monitors, groups, tags, and notifications, and to retrieve heartbeats, stats, and incident history through MCP tools.
      MIT