MCP 服务器

ELK Log Query MCP

Enables querying and searching logs from Kibana (ELK stack) via MCP, with support for project-based data views, trace ID correlation, and log expansion.

README

ELK Log Query MCP

通过 Playwright 登录 Kibana，用 FastMCP 暴露日志查询工具，按项目（Data View / 索引）检索日志。

功能

Tool	说明
`list_projects`	列出 `config.yaml` 中的项目（含 aliases）；`include_remote=true` 时合并 Kibana 全部 Data View
`list_index_patterns`	拉取 Kibana 侧全部 Data View / Index Pattern
`search_logs`	按时间范围 + query_string 查日志；默认 `mode=summary`；可选 `trace_id`
`search_by_trace_id`	按 TraceId / TID 关联查询（默认根 ID，覆盖同链路各 span）
`expand_log_hit`	用摘要命中的 `_index` + `_id` 二次展开完整日志

安装

cd ELK-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
playwright install chromium

配置

cp config.example.yaml config.yaml
# 编辑 config.yaml：填写 base_url、账号密码、项目与 data_view_id 映射

示例：

kibana:
  base_url: "https://elk.dev.jk.com"
  username: "elastic"
  password: "YOUR_PASSWORD"
  headless: true

projects:
  - name: default
    data_view_id: "2eba7c60-6fa0-11f1-adae-c9851401c97f"
    aliases:
      - aas-dev-zs-saas-crm-admin
      - zs-saas-crm-admin
  - name: my-service
    data_view_id: "<another-data-view-id>"
    # 或只用 pattern：
    # index_pattern: "logs-my-service-*"

data_view_id 来自 Discover URL 中的 index='...'。aliases 用于把用户口中的服务名映射到同一 Data View。

本地启动

source .venv/bin/activate
python -m elk_mcp.server
# 或
elk-mcp

接入 Cursor

在 Cursor MCP 配置中加入（路径按本机修改）：

{
  "mcpServers": {
    "elk-logs": {
      "command": "/Users/zhengzihang/Documents/trae_projects/ELK-mcp-server/.venv/bin/python",
      "args": ["-m", "elk_mcp.server"],
      "cwd": "/Users/zhengzihang/Documents/trae_projects/ELK-mcp-server",
      "env": {
        "PYTHONPATH": "/Users/zhengzihang/Documents/trae_projects/ELK-mcp-server/src"
      }
    }
  }
}

若已 pip install -e .，可省略 PYTHONPATH，command 使用 .venv/bin/elk-mcp 亦可。

Agent Skill

项目内 Cursor Skill：.cursor/skills/elk-logs/SKILL.md
指导 Agent 按「摘要 → Trace 关联 → 展开」工作流使用本 MCP（查日志 / TraceId / 排障时自动适用）。

使用示例

list_projects — 查看已配置项目与 aliases
search_logs(project="default", service="zs-saas-crm-admin", query='"queryReceptionDocumentDetail"', from_time="now-1d", size=20)
— 默认摘要：summary + message_preview / level / error_type / trace_id
search_by_trace_id(trace_id="18b3bac3....116....", project="default", from_time="now-1d")
— match=related（默认）用 . 前的根 ID 拉整条链路；match=exact 只匹配完整 span TID
expand_log_hit(index=hit._index, doc_id=hit._id) — 展开完整 message/堆栈
需要列表内直接带 message：mode="full"；total=0 时阅读 hints / meta

说明

会话 Cookie 会持久化到 .elk_session/cookies.json（可用 kibana.cookie_file 覆盖）；启动时优先复用，仅在缺失/探测失败/401/403 时用 Playwright 重新登录，登录后关闭浏览器。
查询走 Kibana HTTP API（Cookie + kbn-xsrf），不解析 Discover DOM。
search_logs 默认 mode=summary，只返回预览与归类摘要；完整日志用 expand_log_hit 二次拉取。
search_by_trace_id 用于链路关联：兼容 [TID:...] / TID: / 原始 ID，默认按根 TraceId 查询并返回 trace_summary。
mode=full 时默认字段仍为 @timestamp + message，长字段头尾截断；fields=["*"] 可拿全文。
kuery / lucene 目前都按 ES query_string 执行；驼峰方法名、接口路径请加引号。
config.yaml 与 .elk_session/ 含敏感信息，已加入 .gitignore，请勿提交。