kibana-claude

用來在 Claude Code 中直接查詢 Kibana log 的 CLI 工具，提供 Claude Code Skills 和 MCP server 兩種整合方式。

不需要直接存取 Elasticsearch — 透過 Kibana 內部 API 進行查詢。

English README

功能特色

• 不依賴 ES 直連：使用 Kibana 內部 HTTP API，無需 Elasticsearch 權限
• Session 自動管理：自動處理 anonymous 登入，401 時自動刷新 session
• 通用 + 專用工具分離：內建工具適用所有 Kibana；各團隊可自行新增專用工具
• Claude Code Skills：預建的 log 搜尋、錯誤分析、摘要 Skill 模板
• MCP Server：讓 Claude Code 能實際執行 Kibana 查詢的工具介面
• TypeScript：完整型別定義

快速開始

# 1. 全域安裝
npm install -g kibana-claude

# 2. 互動式初始化設定
kibana-claude init

# 3. 測試連線
kibana-claude test

# 4. 安裝 Skills 到你的專案
cd your-project
kibana-claude install-skills

# 5. 或設定 MCP server
kibana-claude install-mcp

指令說明

| 指令 | 說明 | |------|------| | kibana-claude init | 互動式設定精靈（Kibana URL、認證方式、預設值） | | kibana-claude test | 測試 Kibana 連線是否正常 | | kibana-claude install-skills | 安裝 Claude Code Skills 到 .claude/skills/ | | kibana-claude install-mcp | 設定 MCP server 到 .claude/mcp.json | | kibana-claude auth | 手動刷新 session | | kibana-claude auth --show | 查看目前 session 資訊 |

運作原理

┌─────────────────────────────────────────────────────┐
│ Claude Code                                         │
│                                                     │
│  Skills (markdown)         MCP Server (stdio)       │
│  ┌──────────────┐         ┌──────────────────┐      │
│  │ search-logs  │         │ search_by_keyword │      │
│  │ error-analysis│        │ get_log_detail    │      │
│  │ log-summary  │         │ refresh_cookie    │      │
│  └──────────────┘         └────────┬─────────┘      │
│                                    │                 │
└────────────────────────────────────┼─────────────────┘
                                     │
                              ┌──────▼──────┐
                              │  Core Lib   │
                              │  auth.ts    │
                              │  search.ts  │
                              │  config.ts  │
                              └──────┬──────┘
                                     │
                              ┌──────▼──────┐
                              │   Kibana    │
                              │ /internal/  │
                              │  bsearch    │
                              └─────────────┘

MCP 工具列表

通用工具（適用所有 Kibana）

| 工具 | 說明 | |------|------| | search_by_keyword | 用關鍵字搜尋 log message | | get_log_detail | 用 _id 取得單筆 log 的完整內容 | | refresh_cookie | 手動刷新 session cookie |

專用工具

各團隊可在 src/mcp/tools/<team-name>/ 下新增自己的工具，並在 src/mcp/server.ts 中註冊。專用工具不會隨 npm 套件發布。

認證方式

目前支援：

• Anonymous（匿名） — 呼叫 /internal/security/login 取得 session cookie，適用於開啟 Guest 存取的 Kibana。401 時自動重新取得 session。

其他認證方式（Basic Auth、API Key）規劃未來版本支援。

設定檔位置

| 範圍 | 路徑 | 用途 | |------|------|------| | 全域 | ~/.kibana-claude/config.json | 跨專案共用設定 | | 專案 | .kibana-claude/config.json | 專案特定設定（優先於全域） | | Session | ~/.kibana-claude/sessions.json | Session cookie（自動管理） |

專案設定檔存在時會覆蓋全域設定。

Skills vs MCP — 如何選擇

Skills 教 Claude Code 如何進行 log 分析（工作流程、查詢策略、輸出格式），是靜態 markdown 檔案，安裝到 .claude/skills/。

MCP Server 賦予 Claude Code 實際執行查詢的能力，以 stdio 背景程序方式運行。

最佳實踐：兩者搭配使用。 Skills 引導 Claude 的分析思路，MCP 提供執行能力。

專案結構

src/
├── lib/                        # 核心函式庫（發布）
│   ├── config.ts               # 設定載入與 session 管理
│   ├── auth.ts                 # 認證（anonymous）
│   ├── search.ts               # Kibana bsearch API 客戶端
│   └── index.ts                # 公開 export 入口
├── mcp/
│   ├── server.ts               # MCP server 入口（發布）
│   ├── formatter.ts            # Log 格式化與異常偵測
│   └── tools/
│       ├── generic/            # 通用工具（發布）
│       │   └── search.ts
│       └── kkday/              # 團隊專用工具（不發布）
│           ├── search-by-uuid.ts
│           ├── search-by-service.ts
│           ├── search-by-product.ts
│           ├── search-by-order.ts
│           └── search-callback.ts
└── cli/                        # CLI 指令（發布）
    ├── index.ts
    └── commands/
        ├── init.ts
        ├── test.ts
        ├── auth.ts
        ├── install-skills.ts
        └── install-mcp.ts
skills/
└── templates/                  # Claude Code Skill 模板（發布）
    ├── search-logs.md
    ├── error-analysis.md
    └── log-summary.md

開發

# 安裝依賴
npm install

# 編譯
npm run build

# 直接執行 MCP server（開發模式）
npm run dev

環境需求

• Node.js >= 18
• 能夠連線到你的 Kibana instance

License

MIT