Uptime Kuma MCP

Kuma MCP服务器正常运行时间

Uptime Kuma的模型上下文协议（MCP）服务器和CLI工具-使AI助手和机器人能够与Uptime Kuma监控系统进行交互。

🌟 特性

• MCP 服务器：通过模型上下文协议与人工智能助手（Claude、OpenClaw bot）集成
• CLI工具：强大的命令行界面，用于管理正常运行时间Kuma
• 插座。IO客户端：与Uptime Kuma服务器实时连接
• API全面覆盖：完全支持Uptime Kuma功能

- 监控管理（HTTP、ping、端口、DNS等） - 状态页面管理 - 事件管理 - 标签和通知管理 - API密钥管理

📦 安装

需求

• Node.js>=20.0.0
• Kuma服务器正常运行时间

从npm安装（发布后）

npm install -g uptime-kuma-mcp

从源代码安装

git clone https://github.com/yourusername/uptime-kuma-mcp.git
cd uptime-kuma-mcp
npm install
npm link

🚀 用法

1.CLI工具

初始配置

# Configure server URL
uptime-kuma config

# Login
uptime-kuma login -u admin -p your-password

# Or login with token
uptime-kuma login -t your-jwt-token

监控管理

# List all monitors
uptime-kuma monitor list

# List as JSON
uptime-kuma monitor list --json

# Get monitor details
uptime-kuma monitor get 1

# Add HTTP monitor
uptime-kuma monitor add \
  -n "My Website" \
  -t http \
  -u https://example.com \
  -i 60

# Add port monitor
uptime-kuma monitor add \
  -n "Database" \
  -t port \
  -h db.example.com \
  -p 5432

# Pause monitor
uptime-kuma monitor pause 1

# Resume monitor
uptime-kuma monitor resume 1

# Delete monitor
uptime-kuma monitor delete 1

# View heartbeats (24h)
uptime-kuma monitor heartbeats 1

# View heartbeats (48h)
uptime-kuma monitor heartbeats 1 -p 48

状态页面管理

# List status pages
uptime-kuma statuspage list

# Or use alias
uptime-kuma sp list

# Create new status page
uptime-kuma statuspage add \
  -t "Service Status" \
  -s service-status

标签管理

# List tags
uptime-kuma tag list

# Add tag
uptime-kuma tag add -n production

# Add tag with color
uptime-kuma tag add -n critical -c "#ff0000"

API密钥管理

# List API keys
uptime-kuma apikey list

# Create new API key
uptime-kuma apikey add -n "API Integration"

# Create API key with expiration
uptime-kuma apikey add -n "Temp Key" -e 2025-12-31

2.MCP服务器

为Claude桌面配置

添加到Claude Desktop配置文件(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "node",
      "args": ["/path/to/uptime-kuma-mcp/src/index.js"],
      "env": {
        "UPTIME_KUMA_URL": "http://localhost:3001",
        "UPTIME_KUMA_TOKEN": "your-jwt-token"
      }
    }
  }
}

或使用用户名/密码

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "node",
      "args": ["/path/to/uptime-kuma-mcp/src/index.js"],
      "env": {
        "UPTIME_KUMA_URL": "http://localhost:3001",
        "UPTIME_KUMA_USERNAME": "admin",
        "UPTIME_KUMA_PASSWORD": "your-password"
      }
    }
  }
}

在Claude中使用

配置后，您可以问Claude：

"List all monitors in Uptime Kuma"
"Create a new HTTP monitor for website https://example.com"
"Create a new status page named 'Service Status'"
"View heartbeats of monitor ID 1 for the past 24h"

3.与OpenClaw Bot集成

OpenClaw机器人可以使用CLI自动化任务：

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

// Create monitor automatically
async function createMonitor(name, url) {
  const { stdout } = await execAsync(
    `uptime-kuma monitor add -n "${name}" -t http -u ${url}`
  );
  console.log(stdout);
}

// Check monitor status
async function checkMonitors() {
  const { stdout } = await execAsync(
    'uptime-kuma monitor list --json'
  );
  const monitors = JSON.parse(stdout);
  return monitors;
}

// Usage
await createMonitor('New Website', 'https://newsite.com');
const monitors = await checkMonitors();
console.log(monitors);

🔧 MCP工具

MCP服务器提供以下工具：

监控管理

• monitor_list -列出所有监视器
• monitor_get -获取监视器详细信息
• monitor_add -添加新监视器
• monitor_edit -编辑监视器
• monitor_delete -删除监视器
• monitor_pause -暂停监视器
• monitor_resume -恢复监视器
• monitor_heartbeats -获取心跳数据

状态页面管理

• statuspage_list -列出状态页面
• statuspage_add -创建新的状态页面
• statuspage_delete -删除状态页
• incident_post -将事件发布到状态页面

标签管理

• tag_list -列表标签
• tag_add -添加新标签

通知管理

• notification_list -列出通知端点
• notification_add -添加通知端点
• notification_test -测试通知

API密钥管理

• apikey_list -列出API密钥
• apikey_add -创建新的API密钥

📝 监视器类型

Uptime Kuma支持多种显示器类型：

• http/https -HTTP端点监控
• 拼 -ICMP ping监控
• 端口 -TCP端口监控
• 域名系统 -DNS解析监控
• 关键词 -带关键字检查的HTTP
• WebSocket -WebSocket连接监控
• 消息队列遥测传输 -MQTT代理监控
• Postgres -PostgreSQL数据库监控
• MySQL -MySQL/MariaDB数据库监控
• MongoDB -MongoDB数据库监控
• 瑞迪斯 -Redis服务器监控
• 码头工人 -Docker容器监控
• grpc关键字 -gRPC服务监控

🔐 认证

JWT代币（推荐）

# Login to get token
uptime-kuma login -u admin -p password

# Token will be saved automatically in config
# Or use existing token
uptime-kuma login -t eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

用户名/密码

uptime-kuma login -u admin -p your-password

环境变量

export UPTIME_KUMA_URL="http://localhost:3001"
export UPTIME_KUMA_TOKEN="your-jwt-token"

# Or
export UPTIME_KUMA_USERNAME="admin"
export UPTIME_KUMA_PASSWORD="your-password"

🛠️ 发展

项目结构

uptime-kuma-mcp/
├── src/
│   ├── index.js              # MCP server main file
│   └── uptime-kuma-client.js # Socket.IO client
├── bin/
│   └── uptime-kuma.js        # CLI tool
├── skills/
│   ├── SKILL.md              # Skill definition (markdown)
│   └── uptime-kuma.json      # Skill metadata
├── package.json
└── README.md

运行开发模式

# MCP server
npm run dev

# CLI tool (after npm link)
uptime-kuma --help

📚 最佳实践

1. 使用JWT令牌 尽可能不存储用户名/密码
2. 设置合理的间隔 （60-300秒）以避免服务器负载过高
3. 使用标签 按环境（生产、暂存等）组织监控器
4. 创建状态页面 让客户查看服务状态
5. 安装通知 在出现问题时接收警报
6. 使用API密钥 带有外部集成的到期日期

🐛 故障排除

连接失败

Error: Failed to connect after maximum attempts

解决方案：

• 检查服务器URL是否正确（包括 http:// 或 https://)
• 确保Kuma服务器正常运行
• 检查防火墙/网络是否阻止连接
• 跑 uptime-kuma config 重新配置

认证失败

Error: Login failed

解决方案：

• 检查用户名/密码是否正确
• 如果使用令牌，请检查令牌是否已过期
• 跑 uptime-kuma login 再次登录
• 如果启用，请检查2FA

监视器不工作

解决方案：

• 检查URL/主机名是否正确
• 检查端口是否打开（用于端口监视器）
• 检查间隔是否合理
• 查看要调试的心跳历史记录：

  uptime-kuma monitor heartbeats 

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🔗 链接

• 正常运行时间Kuma
• 模型上下文协议
• OpenClaw机器人

💡 示例

示例1：为多个网站创建监视器

#!/bin/bash

websites=(
  "https://example.com|Example Site"
  "https://api.example.com|API Server"
  "https://blog.example.com|Blog"
)

for site in "${websites[@]}"; do
  IFS='|' read -r url name  monitors.json

示例3：使用自定义配置创建状态页面

# Create status page
uptime-kuma statuspage add -t "Production Status" -s production

# Then access at:
# http://your-uptime-kuma-server/status/production

示例4：自动暂停/恢复监视器的脚本

#!/bin/bash

# Pause all monitors
for id in $(uptime-kuma monitor list --json | jq -r '.[].id'); do
  uptime-kuma monitor pause $id
done

# Maintenance work here...
sleep 3600

# Resume all monitors
for id in $(uptime-kuma monitor list --json | jq -r '.[].id'); do
  uptime-kuma monitor resume $id
done

🎯 用例

1.自动监控设置

自动为基础架构中的所有服务创建监控器：

const services = [
  { name: 'Web Server', type: 'http', url: 'https://web.example.com' },
  { name: 'API Server', type: 'http', url: 'https://api.example.com' },
  { name: 'Database', type: 'port', hostname: 'db.example.com', port: 5432 },
  { name: 'Redis', type: 'port', hostname: 'redis.example.com', port: 6379 },
];

for (const service of services) {
  // Create monitor using CLI or MCP
}

2.客户状态页面

为每个客户创建单独的状态页面：

uptime-kuma statuspage add -t "Customer A Status" -s customer-a
uptime-kuma statuspage add -t "Customer B Status" -s customer-b

3.与CI/CD集成

部署期间自动暂停监视器，完成后恢复：

# .github/workflows/deploy.yml
- name: Pause monitors
  run: |
    uptime-kuma monitor pause 1
    uptime-kuma monitor pause 2

- name: Deploy application
  run: ./deploy.sh

- name: Resume monitors
  run: |
    uptime-kuma monitor resume 1
    uptime-kuma monitor resume 2

📞 支持

如果您遇到问题或有疑问，请：

• 在GitHub上创建问题
• 通过电子邮件联系：support@example.com
• 加入Discord：Discord.gg/example