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

Type-specific monitor fields

createMonitor and updateMonitor declare the fields most monitors use (url, hostname, port, keyword, interval, …) as ordinary arguments. Everything specific to one kind of monitor goes in a single typeFields object:

createMonitor({ name: "API", type: "http", url: "https://api.example.com/health",
                typeFields: { bearer_token: "…" } })
createMonitor({ name: "Broker", type: "mqtt", hostname: "mqtt://broker.example.com", port: 1883,
                typeFields: { mqttTopic: "sensors/#" } })

getMonitorTypeFields({ type }) lists what a type needs and accepts. The fields are kept out of the tool definitions on purpose: there are about 85 of them, and tool definitions are loaded into every conversation whether or not a monitor is ever created. typeFields is still validated — an unknown name or a bad value is refused, with the accepted spelling suggested.

getMonitor returns these fields at the top level of the monitor, as Uptime Kuma stores them. To change one, pass it inside typeFields.

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":"<client-id>.access","CF-Access-Client-Secret":"<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.

Read-Only Mode

To expose only the tools that report, and none that create, change, pause or delete, set:

UPTIME_KUMA_READ_ONLY=true

The write tools are then not registered at all, so they cannot be called and take up no room in the conversation. Thirteen tools remain: the get… and list… tools, minus getMonitorTypeFields, which only serves the write tools. This limits what the MCP server offers; it does not change what the Uptime Kuma account itself is allowed to do.

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 to 127.0.0.1, so the browser treats requests to your local server as same-origin

• no preflight happens and CORS never applies. The server comparing the Origin header it was sent against a list of expected origins is the only check left standing, which is why the MCP specification makes it a MUST rather than a SHOULD.

If you only use native clients, leaving ALLOWED_ORIGIN unset costs you nothing; those clients send no Origin header. If you use a browser-based client, list its origin:

ALLOWED_ORIGIN=https://librechat.example.com,http://localhost:5173

Running behind a reverse proxy

Without TRUST_PROXY, Express sees every request as coming from the proxy's IP, so the rate limiter puts all of your clients in one shared 100-request bucket and starts returning spurious 429s once traffic from any of them adds up.

Set TRUST_PROXY to the number of proxy hops in front of the server so it reads the real client IP from X-Forwarded-For instead:

TRUST_PROXY=1

Only set this when a proxy you control is actually there to strip and re-set that header. If the server is reachable directly as well, or the proxy passes through whatever X-Forwarded-For it receives, a client can forge that header to get a fresh rate-limit bucket on every request, defeating the limiter entirely.

Credential Redaction

Read tools return *** in place of secrets rather than the values themselves.

Uptime Kuma's socket API returns configuration verbatim - its web UI masks credentials at render time. That is fine for a browser and not fine for an MCP server, whose output lands in an LLM's context window and is then persisted in conversation transcripts, logs and synced history. Asking "what am I monitoring?" should not write a live SMTP password or a third-party API key into storage you may not control.

What is withheld:

hostname, port, url, authMethod, oauth_token_url, oauth_scopes and usernames stay visible: hiding useful configuration is how a redaction feature gets switched off.

To get the real values, either pass includeSecrets: true on the call:

listNotifications({ includeSecrets: true })

or enable it globally:

UPTIME_KUMA_INCLUDE_SECRETS=true

The per-call parameter wins over the environment variable in both directions, so a permissive deployment can still ask one call to redact.

Writing *** back is safe. updateMonitor and updateNotification restore the stored value when a field arrives as the marker, and report which fields they preserved. This matters most for updateNotification: Uptime Kuma replaces the notification row rather than merging it, so without this a read-edit-write round trip would replace a working password with three asterisks. If there is no stored value to restore, the call fails rather than writing a credential that looks set and cannot work.

Push tokens are returned by the call that sets them up. createMonitor returns the token and ping URL of a new push monitor, and updateMonitor does the same when it changes a monitor's type to push, because the sender cannot be wired up without them. Later reads redact the token like any other secret.

Credentials written inline in a URL get the same protection: the url of a monitor, the entries of rabbitmqNodes, and the dockerDaemon of a docker host. A http://***:***@host:2375 read back from a read tool has its userinfo restored from the stored URL rather than persisted verbatim, so editing the path or scheme without re-entering the credentials does not wipe them.

Stored credentials are only restored onto the host and port they were stored for. Sending http://***:***@another-host is refused rather than restored, because that would hand a password you were never shown to an address of the caller's choosing. To point a monitor or docker host at a new address, pass the real credentials along with it.

The MCP logging channel gets the same rule. The debug log for a live heartbeat reports the monitored service's status message by length only (msgLength=...), never its content, since that message can echo a target URL with an embedded user:password@ or a slice of a response body, and on the stdio transport those log notifications reach the client.

LibreChat Configuration

stdio transport:

mcpServers:
  uptime-kuma:
    command: npx
    args: ["-y", "@davidfuchs/mcp-uptime-kuma@latest"]
    env:
      UPTIME_KUMA_URL: "http://your-instance:3001"
      UPTIME_KUMA_USERNAME: "your_username"
      UPTIME_KUMA_PASSWORD: "your_password"
    serverInstructions: true

streamable HTTP transport:

Update the allowed domains to whatever domain you're using in the URL (e.g., localhost or host.docker.internal for Docker setups):

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

mcpSettings:
  allowedDomains:
    - 'mcp-uptime-kuma'

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

Security

To report a vulnerability, please see SECURITY.md.

Disclaimer

This is a personal, free, open-source side project provided "as is" under the MIT License, without warranty of any kind. You install and run it yourself, and it connects to an Uptime Kuma instance that you control. The author is not responsible for any damage, data loss, downtime, or other consequences arising from its use. Use at your own risk.

License

Licensed under the MIT License.