io.github.mshegolev/kibana-mcp

List available Elasticsearch indices. Calls ``GET {ES_URL}/_cat/indices?format=json`` and returns a structured list of indices with health, status, document count, and storage size. Use this first to discover which index names / patterns exist before calling ``kibana_search_logs`` or ``kibana_aggregate_logs``. Examples: - Use when: "What log indices are available in Elasticsearch?" → default params, ``pattern='*'``. - Use when: The user mentions a service name but not the index. Try ``pattern='logs-myservice-*'`` to narrow down. - Use when: "How many documents in the access-log index?" → ``pattern='access-log*'``, check ``docs_count``. - Don't use when: You already know the index name — pass it directly to ``kibana_search_logs`` (saves one round trip). - Don't use when: You need to search log content — that's ``kibana_search_logs``. Returns: dict with keys ``indices_count`` / ``pattern`` / ``include_system`` / ``indices`` (list of {index, health, status, docs_count, store_size_bytes, size_human}).

Search logs using Elasticsearch Query String Syntax. Wraps ``POST {ES_URL}/{index}/_search`` with a ``bool/must`` query. Returns the top matching log entries with their ``_source`` fields. When more than 20 hits are rendered in the text output, a truncation hint is appended — use the structured ``hits`` field for the full list. Examples: - Use when: "Show me the last 20 ERROR logs from the API service." → ``index='logs-*'``, ``query='level:ERROR AND service:api'``. - Use when: "Find 'connection refused' errors in the last hour." → ``query='message:"connection refused"'``, ``time_from='2026-04-18T09:00:00Z'``, ``time_to='2026-04-18T10:00:00Z'``. - Use when: "Show me 500 errors sorted oldest first for replay." → ``query='status:500'``, ``sort_order='asc'``. - Don't use when: You want counts / statistics per field value — use ``kibana_aggregate_logs`` instead (``size:0`` aggregation is much cheaper than retrieving full log documents). - Don't use when: You need more than 500 docs — ES caps ``size`` at 500 via this tool; use scroll API directly for bulk export. Returns: dict with ``total`` / ``returned`` / ``took_ms`` / ``hits`` (list).

Aggregate logs using a terms grouping and optional metric. Wraps ``POST {ES_URL}/{index}/_search`` with ``size:0`` (no hits returned) and a ``terms`` aggregation on ``group_by``. This is the efficient way to get counts, averages, or sums grouped by a field value. When more than 20 buckets are rendered in the text output, a truncation hint is appended — use the structured ``buckets`` field for the full list. Examples: - Use when: "How many logs per log level in the last hour?" → ``index='logs-*'``, ``group_by='level'``, ``time_from='2026-04-18T09:00:00Z'``. - Use when: "What is the average response time per service?" → ``group_by='service.keyword'``, ``metric='avg'``, ``metric_field='response_time_ms'``. - Use when: "Top 10 HTTP status codes today." → ``group_by='http.response.status_code'``, ``size=10``. - Don't use when: You need raw log content/messages — use ``kibana_search_logs`` which returns full ``_source`` objects. - Don't use when: You need time-series (histogram per interval) — that requires a ``date_histogram`` aggregation not supported here. Returns: dict with ``total_documents`` / ``took_ms`` / ``buckets`` (list).

List Kibana saved dashboards. Calls ``GET {KIBANA_URL}/api/saved_objects/_find?type=dashboard``. The ``kbn-xsrf: true`` header is always sent to satisfy Kibana's CSRF guard. Use this to discover dashboard IDs before calling ``kibana_get_dashboard``. Pagination: if ``has_more`` is ``True``, call again with ``page + 1``. Examples: - Use when: "What Kibana dashboards are available?" → default params. - Use when: "Find the infrastructure dashboard." → ``search='infrastructure'``. - Use when: "List all dashboards — page 2." → ``page=2``. - Don't use when: You already have a dashboard ID — use ``kibana_get_dashboard`` directly (one fewer round trip). - Don't use when: You need log content — dashboards contain visualisation config, not raw log data. Use ``kibana_search_logs``. Returns: dict with ``total`` / ``page`` / ``page_size`` / ``has_more`` / ``dashboards`` (list of {id, title, description, updated_at}).

Fetch a single Kibana dashboard with panel details. Calls ``GET {KIBANA_URL}/api/saved_objects/dashboard/{id}``. Returns the dashboard metadata and a summary of contained panels (visualisations, controls, maps, etc.). Examples: - Use when: "What panels does the 'Infrastructure Overview' dashboard have?" → obtain the ID from ``kibana_list_dashboards``, then call with ``dashboard_id=<id>``. - Use when: "Give me the description and panel count of dashboard X." → single call, no search needed if you have the ID. - Use when: Verifying that a dashboard ID from a URL or bookmark is valid. - Don't use when: You don't have the dashboard ID — call ``kibana_list_dashboards`` first with a ``search`` term. - Don't use when: You need log data shown in the dashboard — dashboards contain visualisation config only. Use ``kibana_search_logs`` / ``kibana_aggregate_logs`` for actual data. Returns: dict with ``id`` / ``title`` / ``description`` / ``panels_count`` / ``panels`` (list) / ``updated_at``.