uptime-mcp

uptime-mcp

A Model Context Protocol (MCP) server for Uptime.com. It exposes Uptime.com website, server, and infrastructure monitoring as MCP tools, so AI assistants such as Claude can create and manage checks, read alerts and outages, manage status pages, and inspect account usage on your behalf.

The server speaks two transports: stdio (for local MCP clients like Claude Desktop, Claude Code, and Cursor) and streamable HTTP (for hosted deployments). It authenticates with a static API bearer token or a browser-based OAuth2 PKCE flow.

Claude Code plugin

If you use Claude Code, the easiest way in is the uptime-skills plugin. It bundles this MCP server with task-focused skills — curated context and workflows for Uptime.com (choosing probe locations, tuning outage sensitivity, picking the right check type for a target) — plus a sensible default permission set. The tools alone give Claude the ability to call the API; the skills give it the know-how to use them well, so you get sound monitoring decisions instead of raw API calls.

/plugin marketplace add uptime-com/uptime-skills
/plugin install uptime@uptime-com

Then authenticate (browser OAuth, tokens stored and refreshed for you):

/mcp

See uptime-com/uptime-skills for team and project-level setup.

Hosted server

Uptime.com runs an official hosted instance, so you do not have to run anything yourself. Point any streamable-HTTP MCP client at:

https://mcp.uptime.com/mcp

Authenticate with your Uptime.com API token (generate one under Settings → API & Integrations). Example MCP client configuration:

{
  "mcpServers": {
    "uptime": {
      "type": "http",
      "url": "https://mcp.uptime.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}

The endpoint also advertises RFC 9728 protected-resource metadata, so OAuth2-capable MCP clients can discover the authorization server (https://uptime.com) and obtain tokens themselves instead of supplying a static token.

Prefer to run it yourself? Continue below.

Quick start

The fastest way to try it is with go run (Go 1.26+) and a personal Uptime.com API token. Generate a token in the Uptime.com UI under Settings → API & Integrations, then:

export UPTIME_BEARER_TOKEN=<your-api-token>
go run github.com/uptime-com/uptime-mcp@latest -transport=stdio

Claude Desktop / Claude Code / Cursor (bearer token)

Add the server to your MCP client config (e.g. claude_desktop_config.json, Cursor mcp.json, or claude mcp add-json):

{
  "mcpServers": {
    "uptime": {
      "command": "uptime-mcp",
      "args": ["-transport=stdio"],
      "env": {
        "UPTIME_BEARER_TOKEN": "<your-api-token>"
      }
    }
  }
}

Replace "command": "uptime-mcp" with the absolute path to a downloaded binary, or run the container image:

{
  "mcpServers": {
    "uptime": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "UPTIME_BEARER_TOKEN",
        "ghcr.io/uptime-com/uptime-mcp:latest",
        "-transport=stdio"
      ],
      "env": {
        "UPTIME_BEARER_TOKEN": "<your-api-token>"
      }
    }
  }
}

Claude Desktop (OAuth2, no static token)

Instead of a static token, let the server run a browser-based OAuth2 login on the first tool call. This needs an OAuth application registered in your Uptime.com account (a client ID). No token is stored in your config:

{
  "mcpServers": {
    "uptime": {
      "command": "uptime-mcp",
      "args": [
        "-transport=stdio",
        "-uptime-url=https://uptime.com",
        "-client-id=<your-client-id>"
      ]
    }
  }
}

On the first tool call the server opens your browser to complete authorization, then refreshes the token in the background. See Authentication.

Installation

Prebuilt binary

Download the archive for your platform from the Releases page (Linux, macOS, and Windows on amd64 and arm64), extract it, and put uptime-mcp on your PATH:

tar xzf uptime-mcp_<version>_<os>_<arch>.tar.gz
sudo mv uptime-mcp /usr/local/bin/
uptime-mcp -version

Container image

Published to GitHub Container Registry. Tags: :<version> (immutable, e.g. :0.16.0), :latest (newest stable release), :main (rolling main HEAD).

docker pull ghcr.io/uptime-com/uptime-mcp:latest
docker run -i --rm -e UPTIME_BEARER_TOKEN ghcr.io/uptime-com/uptime-mcp:latest -transport=stdio

Helm chart (HTTP mode on Kubernetes)

Published as an OCI chart. Per-environment URLs are not baked in; set them at install time.

helm install uptime-mcp oci://ghcr.io/uptime-com/uptime-mcp/charts/uptime-mcp \
  --set config.uptimeUrl=https://uptime.com

go install

go install github.com/uptime-com/uptime-mcp@latest

The binary is installed as uptime-mcp in $(go env GOPATH)/bin.

Build from source

git clone https://github.com/uptime-com/uptime-mcp.git
cd uptime-mcp
go build -o uptime-mcp .

Configuration

Configuration is via CLI flags, with environment-variable fallbacks for the sensitive values.

Token environment variable:

Authentication

Bearer token (simplest)

Set UPTIME_BEARER_TOKEN to a pre-obtained Uptime.com API token. Works in both stdio and HTTP modes; the token is forwarded to the Uptime.com API as-is, with no OAuth configuration, verification, or refresh.

UPTIME_BEARER_TOKEN=<your-api-token> uptime-mcp -transport=stdio

OAuth2 (stdio, browser PKCE)

In stdio mode, when UPTIME_BEARER_TOKEN is not set, the server performs a browser-based OAuth2 PKCE flow lazily, on the first tool call rather than at startup. This keeps the MCP handshake (initialize, tools/list) fast. It needs -uptime-url and -client-id; scope api/v1 is requested against <uptime-url>/o/authorize/ and <uptime-url>/o/token/, and tokens are refreshed in the background.

uptime-mcp -transport=stdio \
  -uptime-url=https://uptime.com \
  -client-id=<your-client-id>

HTTP (per-request bearer + RFC 9728 discovery)

In HTTP mode the server is a token passthrough. For each request it resolves a token in this order and forwards it to the Uptime.com API:

When -uptime-url is set, the server also serves RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource, advertising the Uptime.com authorization server and scopes (api/v1, api/v1:read) so OAuth2-capable MCP clients can obtain tokens themselves.

uptime-mcp -transport=http -listen=:8080 \
  -uptime-url=https://uptime.com \
  -client-id=<your-client-id>

Dynamic Client Registration (RFC 7591) is planned, so OAuth2 clients will not need a pre-registered client ID.

HTTP mode and health endpoint

In HTTP mode the server listens on -listen (default :8080) and exposes:

• POST / — the streamable-HTTP MCP endpoint.
• GET /healthz — liveness/readiness probe, returns 204 No Content.
• GET /.well-known/oauth-protected-resource — RFC 9728 metadata (only when -uptime-url is set).

uptime-mcp -transport=http -listen=:8080 -uptime-url=https://uptime.com
curl -i http://localhost:8080/healthz   # -> HTTP/1.1 204 No Content

Features

The server registers tools across the Uptime.com domains below. Tool names are stable; use tools/list from your MCP client to see full input schemas.

Development

Requirements: Go 1.26+.

make test            # run unit tests
make e2e             # run e2e tests (requires UPTIME_BEARER_TOKEN)
make run/http        # run the HTTP server locally on :8080
go build -o uptime-mcp .

The e2e suite talks to a live Uptime.com account and is build-tagged e2e; it runs only when you provide a valid UPTIME_BEARER_TOKEN:

UPTIME_BEARER_TOKEN=<your-api-token> make e2e

Mocks are generated with mockery v3+ (.mockery.yaml).

Contributing

Contributions are welcome. Please open an issue to discuss substantial changes before sending a pull request, keep changes focused, and run make test before submitting. By contributing you agree that your contributions are licensed under the project's MIT license.

License

Licensed under the MIT License. SPDX-License-Identifier: MIT.