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

1. Log into Uptime Kuma web UI
2. Open DevTools → Application → Local Storage
3. Copy the token value
4. 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:

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

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Uptime Kuma GitHub
• Model Context Protocol
• MCP SDK
• Report Issues

👤 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