kibana-mcp

kibana-mcp

面向 Kibana / Elasticsearch 的 MCP 服务——通过 Claude 和任何兼容 MCP 的 Agent 搜索日志、执行聚合、发现索引和浏览仪表板。

为什么还要再做一个 Kibana MCP？

现有集成需要运行中的 Kibana 实例和浏览器级凭据，而且通常封装的是 Kibana UI，而不是稳定的 REST API。此服务：

• 直接调用 Elasticsearch REST API 查询日志（速度更快，且不受 Kibana UI 变更影响）
• 未配置直接 ES URL 时，回退到 Kibana Console 代理（无需额外防火墙规则）
• 支持 ApiKey 身份验证（最适合 Agent），也支持 Basic 身份验证和匿名访问
• 同时返回结构化 JSON（outputSchema）和 Markdown 文本，因此适用于任何 MCP 客户端
• 只读——所有工具均带有 readOnlyHint: true，不会修改数据

工具

工具	API	描述
kibana_list_indices	GET ES/_cat/indices	查看可用索引及其健康状态、文档数和大小
kibana_search_logs	POST ES/{index}/_search	按时间范围、排序方式和数量进行全文日志搜索
kibana_aggregate_logs	POST ES/{index}/_search	按字段分组，并计算 count/avg/sum/min/max 指标
kibana_list_dashboards	GET Kibana/api/saved_objects/_find	搜索并分页列出已保存的仪表板
kibana_get_dashboard	GET Kibana/api/saved_objects/dashboard/{id}	获取单个仪表板及其面板明细

安装

pip install kibana-mcp

或者使用 uvx 直接运行：

uvx kibana-mcp

配置

环境变量

变量	必需	描述
KIBANA_URL	是	Kibana 基础 URL（例如 https://kibana.example.com）
ELASTICSEARCH_URL	否	直接访问 ES 的端点。未设置时，ES 请求会通过 Kibana Console 代理
KIBANA_API_KEY	否	ES API 密钥（ApiKey base64(id:api_key) 格式）。推荐用于 Agent
KIBANA_USERNAME	否	HTTP Basic 身份验证用户名（未设置 API 密钥时使用）
KIBANA_PASSWORD	否	HTTP Basic 身份验证密码
KIBANA_SSL_VERIFY	否	true（默认值）或 false，用于自签名证书

身份验证优先级：ApiKey > Basic > 匿名。

将 .env.example 复制为 .env，并填写相应值。

MCP 客户端配置（Claude Desktop / claude.app）

{
  "mcpServers": {
    "kibana": {
      "command": "uvx",
      "args": ["kibana-mcp"],
      "env": {
        "KIBANA_URL": "https://kibana.example.com",
        "KIBANA_API_KEY": "your-api-key-here"
      }
    }
  }
}

或者使用直接 ES 访问以获得更佳性能：

{
  "mcpServers": {
    "kibana": {
      "command": "uvx",
      "args": ["kibana-mcp"],
      "env": {
        "KIBANA_URL": "https://kibana.example.com",
        "ELASTICSEARCH_URL": "https://es.example.com:9200",
        "KIBANA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Docker

docker run --rm -i \
  -e KIBANA_URL=https://kibana.example.com \
  -e KIBANA_API_KEY=your-key \
  ghcr.io/mshegolev/kibana-mcp

使用示例

日志搜索

Find the last 50 ERROR logs from the API service in the last hour

→ kibana_search_logs(index="logs-*", query="level:ERROR AND service:api", size=50, time_from="2026-04-18T09:00:00Z")

Show 500 HTTP errors sorted oldest first for incident replay

→ kibana_search_logs(index="nginx-*", query="status:500", sort_order="asc", size=100)

聚合

How many logs per log level in the last hour?

→ kibana_aggregate_logs(index="logs-*", group_by="level", time_from="2026-04-18T09:00:00Z")

What is the average response time per service?

→ kibana_aggregate_logs(index="logs-*", group_by="service.keyword", metric="avg", metric_field="response_time_ms")

索引发现

What log indices are available?

→ kibana_list_indices()

Show me all filebeat indices

→ kibana_list_indices(pattern="filebeat-*")

仪表板

Find the infrastructure dashboard

→ kibana_list_dashboards(search="infrastructure")

What panels does dashboard X have?

→ kibana_get_dashboard(dashboard_id="<id from list_dashboards>")

性能特征

• 日志搜索（kibana_search_logs）：直接使用 ES URL 时通常为 50-500 ms；通过 Kibana Console 代理路由时会增加 100-200 ms
• 聚合（kibana_aggregate_logs）：size:0 查询不会传输命中结果，通常为 10-100 ms
• 索引列表：调用一次 _cat/indices，响应大小为 O(index_count)，通常 <100 ms
• 仪表板 API：Kibana Saved Objects API，通常为 50-200 ms；延迟来自 Kibana 端，而非网络
• 如果 Agent 经常搜索日志，请直接设置 ELASTICSEARCH_URL，以消除代理开销

开发

git clone https://github.com/mshegolev/kibana-mcp
cd kibana-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

许可证

MIT — 请参阅 LICENSE。