HertzBeat 日志 MCP

该 MCP 服务基于 GreptimeDB 查询 HertzBeat 自身运行日志。使用前需要启用 GreptimeDB 日志写入。

结构化只读查询

服务只暴露 query_logs，不再接收或执行调用方提供的 SQL。服务端生成的查询固定为：

SELECT timestamp, severity_text, body
FROM hzb_logs
WHERE <结构化过滤条件>
ORDER BY timestamp DESC
LIMIT <1-100>

query_logs 支持以下可选参数：

参数	类型	说明
`severity`	字符串	`TRACE`、`DEBUG`、`INFO`、`WARN`、`ERROR` 或 `FATAL`
`keyword`	字符串	日志正文关键词，最长 256 个字符
`startTime`	整数	开始时间，Unix 毫秒时间戳
`endTime`	整数	结束时间，Unix 毫秒时间戳
`limit`	整数	返回条数，默认为 20，范围为 1～100

调用示例：

{
  "severity": "ERROR",
  "keyword": "connection refused",
  "startTime": 1783785600000,
  "endTime": 1783872000000,
  "limit": 20
}

当前 hzb_logs 表没有 monitorId 字段，因此本接口不提供无效的监控 ID 过滤。如果后续需要该能力，应先在 OpenTelemetry 日志写入链中定义并提取统一的监控 ID 字段。

GreptimeDB 账号

服务支持通过 greptime.username 和 greptime.password 发送 HTTP Basic Authentication。用户名和密码必须同时配置；建议配合 HTTPS 或可信内网使用。

项目当前 Docker Compose 使用 GreptimeDB v0.14.3，该版本只提供身份认证，不能限制用户为只读权限。因此当前真正生效的安全边界是“删除原始 SQL参数并固定生成单条 SELECT”。使用 GreptimeDB 1.0 及以上版本时，应为该 MCP 配置独立的 ro/readonly 账号。

Claude Desktop 集成（stdio）

{
    "mcpServers": {
        "hertzbeat-mcp": {
            "command": "java",
            "args": [
                "-Dspring.ai.mcp.server.stdio=true",
                "-Dspring.main.web-application-type=none",
                "-Dlogging.pattern.console=",
                "-jar",
                "${PATH}/hertzbeat-mcp-2.0-SNAPSHOT.jar"
            ],
            "env": {
                "GREPTIME_URL": "http://${IP}:4000",
                "GREPTIME_DATABASE": "public",
                "GREPTIME_USERNAME": "${READ_ONLY_USERNAME}",
                "GREPTIME_PASSWORD": "${READ_ONLY_PASSWORD}"
            }
        }
    }
}

不启用 GreptimeDB 认证时，可以省略 GREPTIME_USERNAME 和 GREPTIME_PASSWORD；不能只配置其中一个。

旧的 getHertzbeatLog({"querySql": "..."}) Tool 已直接移除，不保留兼容入口，以免继续暴露任意 SQL执行能力。

README.md Unescape Escape

HertzBeat 日志 MCP

结构化只读查询

GreptimeDB 账号

Claude Desktop 集成（stdio）

README.md