kibana-mcp-server

v0.1.0

Published

10 months ago

Model Context Protocol server for kibana query

Downloads

0High
0Medium
0Low

uniqueli

kibana query mcp typescript

Kibana Query MCP

这是一个基于 Model Context Protocol (MCP) 的 Kibana 日志查询服务，提供与 AI 助手集成的日志查询能力。

功能特点

提供 Kibana 日志查询 API，支持简单和高级查询场景
支持多种查询过滤条件和复杂查询参数
内置聚合查询功能，用于数据分析和可视化
支持桶过滤聚合，方便对数据进行分类统计
返回查询结果和对应的 Kibana 链接，方便跳转到 Kibana 查看完整数据
支持认证 Cookie，允许查询需要登录的 Kibana 实例

安装

打开cursor setting，选择MCP 功能，设置如下：

"kibana-devloper-mcp": {
  "command": "npx",
  "args": ["-y", "kibana-mcp-server@latest", "--stdio"]
}

API 说明

本 MCP 提供三种查询接口，根据需求选择使用。

1. 标准查询 (kibana_query)

支持简单查询和复杂过滤条件的通用查询接口。

{
  "name": "kibana_query",
  "params": {
    "kibanaUrl": "https://kibana-example.com/app/kibana",
    "index": "basiclog-sys_1001128-*",
    "query": "ERROR",
    "timeRange": {
      "from": "now-7d",
      "to": "now"
    },
    "filters": [
      {
        "field": "data.type",
        "operator": "is",
        "value": "PV"
      },
      {
        "field": "service",
        "operator": "contains",
        "value": "api"
      }
    ],
    "size": 500,
    "sort": [
      {
        "field": "@timestamp",
        "order": "desc"
      }
    ],
    "cookie": "session=abc123; auth=xyz456"
  }
}

也支持简化的时间范围格式（向后兼容）：

{
  "name": "kibana_query",
  "params": {
    "kibanaUrl": "https://kibana-example.com/app/kibana",
    "index": "basiclog-sys_1001128-*",
    "query": "ERROR",
    "timeFrom": "now-24h",
    "timeTo": "now",
    "size": 500,
    "cookie": "session=abc123; auth=xyz456"
  }
}

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | kibanaUrl | string | 是 | Kibana 服务器 URL | | index | string | 是 | Kibana 索引名称，支持通配符 | | query | string | 否 | 查询字符串，支持 Lucene 语法 | | timeRange | object | 否 | 查询时间范围（结构化格式） | | timeRange.from | string/number | 是 | 开始时间，支持相对时间或时间戳 | | timeRange.to | string/number | 是 | 结束时间，支持相对时间或时间戳 | | timeFrom | string | 否 | 查询时间范围开始（简化格式） | | timeTo | string | 否 | 查询时间范围结束（简化格式） | | filters | array | 否 | 查询过滤条件 | | filters[].field | string | 是 | 字段名称 | | filters[].operator | string | 是 | 操作符，支持 is/is not/contains/does not contain/exists/does not exist/>/>=/</<= | | filters[].value | any | 否 | 过滤值（对于 exists/does not exist 可省略） | | size | number | 否 | 返回的日志条数，默认 500 条 | | sort | array | 否 | 排序条件 | | sort[].field | string | 是 | 排序字段 | | sort[].order | string | 是 | 排序方向，asc 或 desc | | cookie | string | 否 | 认证 Cookie |

2. 聚合查询 (kibana_aggregation)

支持 Elasticsearch 聚合查询，用于数据分析和统计。

{
  "name": "kibana_aggregation",
  "params": {
    "kibanaUrl": "https://kibana-example.com/app/kibana",
    "index": "basiclog-sys_1001128-*",
    "timeField": "bus_@timestamp",
    "timeRange": {
      "from": 1747488976896,
      "to": 1747575376896
    },
    "mustFilters": [
      {
        "type": "match_phrase",
        "field": "request.keyword",
        "value": "POST /v1/student/duration/push HTTP/1.1"
      },
      {
        "type": "match_phrase",
        "field": "domain.keyword",
        "value": "studentlive.example.com"
      }
    ],
    "aggregations": {
      "status_terms": {
        "terms": {
          "field": "status.keyword",
          "size": 10
        }
      }
    },
    "cookie": "session=abc123; auth=xyz456"
  }
}

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | kibanaUrl | string | 是 | Kibana 服务器 URL | | index | string | 是 | Kibana 索引名称 | | timeField | string | 否 | 时间字段名称，默认为 @timestamp | | timeRange | object | 是 | 查询时间范围 | | timeRange.from | string/number | 是 | 开始时间 | | timeRange.to | string/number | 是 | 结束时间 | | filters | array | 否 | 一般过滤条件 | | filters[].field | string | 是 | 字段名称 | | filters[].value | any | 是 | 过滤值 | | filters[].operator | string | 否 | 操作符，默认 is | | filters[].query_string | boolean | 否 | 是否使用 query_string 查询 | | mustFilters | array | 否 | 必须匹配的过滤条件 | | mustFilters[].type | string | 是 | 过滤类型：match_phrase/term/query_string | | mustFilters[].field | string | 是 | 字段名称 | | mustFilters[].value | any | 是 | 过滤值 | | aggregations | object | 是 | 聚合配置 | | cookie | string | 是 | 认证 Cookie |

3. 过滤聚合查询 (kibana_filters_aggregation)

专用于 Filters 聚合，将数据分成不同的桶进行计数。

{
  "name": "kibana_filters_aggregation",
  "params": {
    "kibanaUrl": "https://kibana-example.com/app/kibana",
    "index": "basiclog-access-*",
    "timeField": "bus_@timestamp",
    "timeRange": {
      "from": 1747488976896,
      "to": 1747575376896
    },
    "mustFilters": [
      {
        "type": "match_phrase",
        "field": "request.keyword",
        "value": "POST /v1/student/duration/push HTTP/1.1"
      },
      {
        "type": "match_phrase",
        "field": "domain.keyword",
        "value": "studentlive.example.com"
      }
    ],
    "filterBuckets": {
      "模式A": {
        "query_string": "\"\\\"gameMode5v5\\\":2\""
      },
      "模式B": {
        "query_string": "\"\\\"gameMode5v5\\\":1\""
      }
    },
    "cookie": "session=abc123; auth=xyz456"
  }
}

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | kibanaUrl | string | 是 | Kibana 服务器 URL | | index | string | 是 | Kibana 索引名称 | | timeField | string | 否 | 时间字段名称，默认根据索引名自动判断 | | timeRange | object | 是 | 查询时间范围 | | timeRange.from | string/number | 是 | 开始时间 | | timeRange.to | string/number | 是 | 结束时间 | | mustFilters | array | 否 | 必须匹配的过滤条件 | | mustFilters[].type | string | 是 | 过滤类型 | | mustFilters[].field | string | 是 | 字段名称 | | mustFilters[].value | any | 是 | 过滤值 | | filterBuckets | object | 是 | 定义不同的过滤桶 | | filterBuckets.{桶名称} | object | 是 | 桶配置 | | filterBuckets.{桶名称}.query_string | string | 是 | 桶的查询条件 | | cookie | string | 是 | 认证 Cookie |

特定场景示例

示例：查询错误日志

{
  "name": "kibana_query",
  "params": {
    "kibanaUrl": "https://kibana-example.com/app/kibana",
    "index": "basiclog-sys_1001128-*",
    "query": "level:ERROR",
    "timeRange": {
      "from": "now-24h",
      "to": "now"
    },
    "size": 100,
    "cookie": "session=abc123; auth=xyz456"
  }
}

示例：统计不同状态码的数量

{
  "name": "kibana_aggregation",
  "params": {
    "kibanaUrl": "https://kibana-example.com/app/kibana",
    "index": "basiclog-access-*",
    "timeRange": {
      "from": "now-7d",
      "to": "now"
    },
    "aggregations": {
      "status_codes": {
        "terms": {
          "field": "status.keyword",
          "size": 20
        }
      }
    },
    "cookie": "session=abc123; auth=xyz456"
  }
}

示例：比较不同类型请求的数量

{
  "name": "kibana_filters_aggregation",
  "params": {
    "kibanaUrl": "https://kibana-example.com/app/kibana",
    "index": "basiclog-access-*",
    "timeRange": {
      "from": "now-24h",
      "to": "now"
    },
    "filterBuckets": {
      "GET请求": {
        "query_string": "request:GET*"
      },
      "POST请求": {
        "query_string": "request:POST*"
      },
      "其他请求": {
        "query_string": "NOT request:GET* AND NOT request:POST*"
      }
    },
    "cookie": "session=abc123; auth=xyz456"
  }
}

注意事项

必须通过参数传入 Kibana 服务器 URL 和索引名称
使用 cookie 进行认证的查询，需要确保 cookie 是有效的，通常可以从浏览器中复制
时间范围支持两种格式：
- 相对时间：如 now-24h, now-7d
- 时间戳（毫秒）：如 1747306863970
索引名称需要完整指定，支持通配符，如 basiclog-sys_1001128-*
聚合查询默认不返回实际文档，只返回聚合结果
过滤桶查询返回的是每个桶的文档计数，便于快速比较不同条件下的数据量

开发

# 安装依赖
pnpm install

# 开发模式运行
pnpm dev

# 构建
pnpm build

# 发布
pnpm pub:release

配置参数

| 参数 | 说明 | 默认值 | | --- | --- | --- | | port | 服务器端口 | 3333 |

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Kibana Query MCP

功能特点

安装

API 说明

1. 标准查询 (kibana_query)

参数说明

2. 聚合查询 (kibana_aggregation)

参数说明

3. 过滤聚合查询 (kibana_filters_aggregation)

参数说明

特定场景示例

示例：查询错误日志

示例：统计不同状态码的数量

示例：比较不同类型请求的数量

注意事项

开发

配置参数

许可证