Uptime Kuma API Bridge

Private REST/MCP API to provision and synchronize Uptime Kuma HTTP (S) monitors and groups from an external system. Uptime Kuma (GitHub)has no built-in REST API for monitors. Everything goes through socket.io events driven by its own frontend. This bridge connects to Uptime Kuma as an authenticated socket.io client (like a logged-in browser tab) and translates REST calls into those same native events (add, editMonitor, pauseMonitor, resumeMonitor, deleteMonitor, getMonitor, getMonitorList), so Uptime Kuma's own business logic keeps its database, its in-memory monitor registry, and its scheduler in sync. The bridge never writes to Uptime Kuma's database directly.

Used by the MainWP Uptime Kuma Extension to sync MainWP child sites to Uptime Kuma, but usable standalone by anything that can call a REST API or an MCP tool.

This is an independent, community project. It is not affiliated with, endorsed by, or supported by the Uptime Kuma project.

Compatibility

The bridge relies on Uptime Kuma's internal socket.io events and payload shapes (add, editMonitor, getMonitorChartData, monitorImportantHeartbeatListPaged, etc.); these are not a documented public contract, so a future Uptime Kuma release could change their shape and break the bridge silently. Pin your Uptime Kuma instance to a known-working version before upgrading it blindly, and treat unexpected errors right after an Uptime Kuma upgrade as the first suspect.

Related MCP server: mcp-uptime-kuma

Requirements

• A dedicated Uptime Kuma user account for the bridge to log in as (UPTIME_KUMA_SERVICE_*), with 2FA disabled (the bridge doesn't handle 2FA challenges). Uptime Kuma scopes monitors by owner, so this account can only manage monitors/groups it created itself. On a single-admin Uptime Kuma instance (the common case), that account already owns everything.

• Node.js >= 22, pnpm.

Configuration

Copy .env.example to .env and fill in the values. Two independent secrets:

• BRIDGE_AUTH_TOKEN: protects this bridge's own REST API. Send it as Authorization: Bearer <token> on every request. Unrelated to Uptime Kuma's own accounts/API keys: Uptime Kuma has no way to authenticate a socket.io session with an API key, only username/password or a JWT derived from one.

• UPTIME_KUMA_SERVICE_USERNAME / UPTIME_KUMA_SERVICE_PASSWORD: the Uptime Kuma account the bridge logs in as to drive monitors.

Development

git clone https://github.com/gaido-dev/uptime-kuma-api-bridge.git
cd uptime-kuma-api-bridge
pnpm install
pnpm dev        # tsx watch
pnpm typecheck
pnpm build      # tsdown -> dist/
pnpm start      # run the built output

API

Interactive OpenAPI docs are served at GET /docs (publicly reachable, it only exposes route shapes, not monitor data). All /api/v1/* routes require the bearer token.

GET /health and GET /ready are unauthenticated liveness/readiness probes; /ready returns 503 while the socket.io connection to Uptime Kuma isn't established.

Stats caveat: cert/domain expiry can start out null

Uptime Kuma has no request/response event for certificate or domain expiry: it only pushes that data after each heartbeat cycle. The bridge caches the latest push per monitor, so certInfo/domainDaysRemaining/domainExpiresOn in GET /monitors/:id/stats read null until that monitor's next check completes after the bridge (re)connects, same as a freshly opened Uptime Kuma browser tab would show. uptime24h/ uptime30d/uptime1y/avgPing24h, by contrast, are computed on demand from getMonitorChartData and are always fresh.

MCP (LLM tool access)

Besides the REST API, the bridge exposes the same service layer as MCP tools over POST /mcp (Streamable HTTP, stateless, no session to manage), so an LLM client (Claude Desktop, an internal agent, etc.) can drive Uptime Kuma directly. It requires the same Authorization: Bearer <BRIDGE_AUTH_TOKEN> header as the REST API. There's no separate MCP auth to configure.

Available tools: monitors_list, monitors_get, monitors_create, monitors_update, monitors_pause, monitors_resume, monitors_delete, monitors_heartbeats, monitors_chart, monitors_important_events, monitors_stats, groups_list, groups_create, notifications_list, tags_list, tags_create, tags_update, tags_delete. Each is a thin wrapper around the same MonitorService/GroupService/NotificationService/TagService methods the REST routes call: same zod schemas, same validation, same errors.

Example Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "uptime-kuma-rest": {
      "url": "http://localhost:3050/mcp",
      "headers": {
        "Authorization": "Bearer <BRIDGE_AUTH_TOKEN>"
      }
    }
  }
}

To test manually without a full LLM client, use the MCP Inspector:

npx @modelcontextprotocol/inspector

Then connect it to http://localhost:3050/mcp (Streamable HTTP transport) with the bearer token header set, and call tools directly from its UI.

Manual testing

• GET /docs: interactive Swagger UI, generated live from the app's zod schemas. Click "Authorize", paste the bearer token, and try any request straight from the browser, no extra tool needed. GET /docs/json serves the same spec as raw JSON.

• openapi.json: the same OpenAPI 3 spec, committed at the project root (pnpm openapi regenerates it after any route/DTO change). Import it into Postman (Import > File) or Insomnia to get every route pre-built, grouped by tag (Monitors/Groups/Tags/Notifications/Health); both will prompt for the baseUrl server variable and the bearer token on import. Prefer the live GET /docs/json over this static file if you suspect it has drifted from a deployed instance.

Error responses

Docker

docker build -t uptime-kuma-api-bridge .

See docker-compose.example.yml for running it alongside an uptime-kuma service. The bridge only needs network access to Uptime Kuma. No shared volume or database access required.

Security notes

• The bridge has no TLS of its own. Put it behind a reverse proxy that terminates HTTPS (nginx, Caddy, Traefik) and don't expose the plain HTTP port directly to the internet.

• BRIDGE_AUTH_TOKEN is the only thing standing between anyone reaching the bridge and full control over your Uptime Kuma monitors (create/update/delete). Treat it like a credential: generate it randomly, never commit it, and rotate it if it ever leaks.

• There's currently no rate limiting on the API. Combined with the single static bearer token, that means a leaked token can be used at will until rotated; there's no lockout to slow down repeated failed attempts either.

• GET /docs (and /docs/json) is intentionally left unauthenticated: it only serves the OpenAPI schema (route shapes and field names), never monitor data.

License

MIT. See LICENSE.