uptime-kuma-mcp-server
Connect an MCP client to Uptime Kuma to inspect, manage, and monitor checks plus read operational metrics.
List/search/paginate monitors and get single-monitor details.
Create, edit, delete, pause, and resume monitors (HTTP, keyword, port, ping, DNS, push; Steam/MQTT/Docker not exposed for creation).
Retrieve recent heartbeats and summarize uptime ratio/average ping over a period.
List notification channels and status pages without exposing credentials.
Fetch Prometheus metrics from Uptime Kuma’s authenticated
/metricsendpoint.Use either stdio or local authenticated Streamable HTTP transport.
Provides tools for interacting with an Uptime Kuma instance, enabling management of monitors (create, edit, delete, pause, resume), retrieval of heartbeats, uptime status, Prometheus metrics, notifications, and status pages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@uptime-kuma-mcp-server Create an HTTP monitor for https://example.com every 60s and notify via Slack"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 testRelated 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.jsPoint 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: | Behavior |
| Search and paginate monitor configuration |
| Read one monitor without credential fields |
| Create an HTTP, keyword, port, ping, DNS or push monitor |
| Merge provided fields; active changes invoke Kuma pause/resume |
| Delete a monitor and its history |
| Stop/start monitoring |
| Recent checks, newest first |
| Successful-check ratio and weighted average ping from Kuma chart buckets |
| Channel ID, name, type and active state; credentials omitted |
| Status-page configuration |
| Prometheus exposition from authenticated |
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 testTo 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:liveThe 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 toolsuptime_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 MonitorADestructiveIdempotent
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 MonitorAIdempotent
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 HeartbeatsARead-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 MetricsARead-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 MonitorARead-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 StatusARead-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 MonitorsARead-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 NotificationsARead-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 PagesARead-onlyIdempotent
List public status pages.
Returns id/slug/title/published.
Inputs: response_format.
uptime_kuma_pause_monitorPause Uptime Kuma MonitorAIdempotent
Pause heartbeat checks for a monitor (sets active=false).
Args: monitor_id
Inputs: monitor_id (required).
uptime_kuma_resume_monitorResume Uptime Kuma MonitorAIdempotent
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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
Uptime monitoring: monitors, incidents, status pages; create, pause and acknowledge.
Create, test, and manage uptime monitors for websites and APIs from your AI agent.
Monitor websites, APIs, and servers: create monitors, triage incidents, and query uptime stats.
Manage scheduled requests, uptime monitors and heartbeats from your AI assistant.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with Uptime Agent monitoring system to check uptime status, manage incidents, create new monitors, and analyze downtime through natural conversation.71MIT
- AlicenseAqualityDmaintenanceEnables managing UptimeRobot monitors, alert contacts, and maintenance windows via natural language through the MCP protocol.16MIT
- AlicenseAqualityCmaintenanceEnables 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.71MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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