Uptime Kuma MCP Server

A Model Context Protocol (MCP) server for Uptime Kuma monitoring. Connect any MCP-compatible AI client (Claude, Codex, Hermes, Cline) to your Uptime Kuma instance and query monitor status, get alerts, and manage your infrastructure through natural language.

🎯 What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external tools and data sources. This server acts as a bridge between your AI assistant and Uptime Kuma monitoring.

✨ Features

🔌 Universal Compatibility: Works with Claude Desktop, OpenAI Codex, Cline, Hermes, and any MCP client
📊 Monitor Status: Get real-time status of all your Uptime Kuma monitors
🚨 Down Service Alerts: Instantly see which services are down
📈 Uptime Statistics: View 24h, 7d, and 30-day uptime percentages
🔍 Search & Filter: Search monitors by name or URL
📜 Heartbeat History: View recent check history for any monitor
📢 Notifications: List configured notification channels
🏷️ Tags & Groups: Organize monitors by tags
🔧 Maintenance Windows: View scheduled maintenance

🚀 Quick Start

Prerequisites

Node.js 18+ installed
Uptime Kuma instance running

Installation

# Clone the repository
git clone https://github.com/kobidkunda/uptime-kuma-mcp-server.git
cd uptime-kuma-mcp-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Configuration

Set environment variables:

export UPTIME_KUMA_URL="http://your-uptime-kuma:3001"
export UPTIME_KUMA_USERNAME="your-username"
export UPTIME_KUMA_PASSWORD="your-password"

# Optional: For 2FA users, use JWT token instead
export UPTIME_KUMA_JWT_TOKEN="your-jwt-token"

Testing

# Quick test
node dist/index.js

🔧 Client Configuration

Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "node",
      "args": [
        "/path/to/uptime-kuma-mcp-server/dist/index.js"
      ],
      "env": {
        "UPTIME_KUMA_URL": "http://192.168.88.96:6754",
        "UPTIME_KUMA_USERNAME": "biolastic",
        "UPTIME_KUMA_PASSWORD": "Kobid@1993"
      }
    }
  }
}

OpenAI Codex

Add to your Codex MCP configuration:

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "node",
      "args": ["/path/to/uptime-kuma-mcp-server/dist/index.js"],
      "env": {
        "UPTIME_KUMA_URL": "http://192.168.88.96:6754",
        "UPTIME_KUMA_USERNAME": "biolastic",
        "UPTIME_KUMA_PASSWORD": "Kobid@1993"
      }
    }
  }
}

Cline (VS Code Extension)

Add to Cline MCP settings:

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "node",
      "args": ["/path/to/uptime-kuma-mcp-server/dist/index.js"],
      "env": {
        "UPTIME_KUMA_URL": "http://192.168.88.96:6754",
        "UPTIME_KUMA_USERNAME": "biolastic",
        "UPTIME_KUMA_PASSWORD": "Kobid@1993"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Hermes

Add to ~/.config/hermes/mcp/mcp-servers.yaml:

servers:
  uptime-kuma:
    command: node
    args:
      - /path/to/uptime-kuma-mcp-server/dist/index.js
    env:
      UPTIME_KUMA_URL: http://192.168.88.96:6754
      UPTIME_KUMA_USERNAME: biolastic
      UPTIME_KUMA_PASSWORD: Kobid@1993

🛠️ Available Tools

Once connected, your AI assistant can use these tools:

| Tool | Description | Example Query | |------|-------------|---------------| | getStatus | Overall status summary | "What's the status of all monitors?" | | listMonitors | List all monitors | "Show me all my monitors" | | getDownServices | List down services | "Which services are down?" | | getMonitorDetails | Get specific monitor info | "Tell me about the 'API Server' monitor" | | getHeartbeats | View check history | "Show recent checks for the database" | | getMonitorUptime | Uptime statistics | "What's the uptime for my website?" | | searchMonitors | Search monitors | "Find monitors related to 'api'" | | listNotifications | Notification channels | "What notifications are configured?" | | listTags | List all tags | "Show me all tags" | | getMaintenanceWindows | Scheduled maintenance | "Are there any maintenance windows?" | | getStatusPages | Public status pages | "List my status pages" |

💬 Example Conversations

With Claude:

"What's the current status of my infrastructure?"

Response:

I can see you have 53 monitors total:

UP: 48 ✅

DOWN: 2 ❌ (Database Server, Payment API)

PENDING: 1 ⏳

PAUSED: 2 ⏸️

The down services are:

Database Server (last seen 12 minutes ago)

Payment API (last seen 45 minutes ago)

With Codex:

"Check my website uptime for the last 7 days"

Response:

Your website (https://example.com) has:

7-day uptime: 99.2%

24-hour uptime: 100%

Current status: ✅ UP

Last check: 2 minutes ago

🔐 Authentication Methods

Option 1: Username/Password (Default)

export UPTIME_KUMA_USERNAME="your-username"
export UPTIME_KUMA_PASSWORD="your-password"

Option 2: JWT Token (Recommended for 2FA users)

Get your JWT token:

npx -p @davidfuchs/mcp-uptime-kuma mcp-uptime-kuma-get-jwt \
  http://your-uptime-kuma:3001 \
  your-username \
  'your-password'

Then use:

export UPTIME_KUMA_JWT_TOKEN="<your-jwt-token>"

Option 3: Browser Token

Log into Uptime Kuma web UI
Open DevTools → Application → Local Storage
Copy the token value
Set as UPTIME_KUMA_JWT_TOKEN

🐛 Troubleshooting

Connection Timeout

Verify Uptime Kuma is running: curl http://your-uptime-kuma:3001
Check firewall settings
Ensure Socket.IO is enabled

Authentication Failed

Verify credentials
Check if 2FA is enabled (use JWT token)
Try browser token method

MCP Client Not Recognizing Tools

Restart the MCP client after configuration
Check client logs for connection errors
Verify the server started without errors

🏗️ Architecture

┌─────────────────┐     MCP Protocol      ┌──────────────────┐     Socket.IO      ┌──────────────┐
│  AI Assistant   │ ◄──────────────────► │  MCP Server      │ ◄───────────────► │  Uptime      │
│  (Claude/Codex) │   (stdio/stdio)       │  (Node.js)       │   (WebSocket)     │  Kuma        │
│                 │                       │                  │                   │  Server      │
└─────────────────┘                       └──────────────────┘                   └──────────────┘

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Commit changes: git commit -am 'Add my feature'
Push to branch: git push origin feature/my-feature
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

👤 Author

Kobid Kunda

GitHub: @kobidkunda
Email: devops@biolastic.co.in

🌟 Star History

If you find this project useful, please consider giving it a star! It helps others discover the project.

Keywords: Uptime Kuma, MCP, Model Context Protocol, AI monitoring, Claude, Codex, Cline, Hermes, infrastructure monitoring, Socket.IO, TypeScript, Node.js, Telegram alerts, webhook monitoring, status page, uptime monitoring, DevOps, SRE, observability

MCP Servers