mcp-for-kibana

An MCP server for Kibana: composable toolboxes over a hexagonal core, powered by kibana-py.

Disclaimer: This is an independent, community-driven project and is not officially affiliated with, endorsed by, or supported by Elastic N.V. or any of its subsidiaries. "Kibana" and "Elasticsearch" are trademarks of Elastic N.V. This project is provided "as is", without warranty of any kind. See LICENSE. The name "mcp-for-kibana" uses "Kibana" referentially — this is an MCP server for Kibana, per Elastic's trademark guidelines on referential use — and does not imply origin or endorsement.

The distribution is mcp-for-kibana; the Python import package is kibana_mcp.

Technical Preview: the dashboards toolbox is built entirely on Kibana 9.4's new public Dashboards API and Visualizations API, both marked x-state: Technical Preview by Elastic — their request/response shapes may still change in a later Kibana release without notice, and they carry no support SLA. This server targets Kibana 9.4+ only; earlier versions don't expose these APIs publicly at all.

Status

v0.1.0 — 10 toolboxes, 133 tools, live-tested. The server exposes 133 tools across 10 composable toolboxes (dashboards, data management, alerting, cases, security detections, fleet, streams, observability, platform admin, and platform health), each classified read / write / destructive and contract-tested against a live Kibana 9.4.3. It's packaged as a stdio and container-runnable server. See the Tool reference below.

The flagship path is dashboards from plain English: an LLM goes from a request ("average ticket price by carrier, last 7 days") to a real Kibana dashboard through the read → validate → translate → write flow. That path passed its end-to-end gate 3/3 on 2026-07-10: a real local LLM in LM Studio (openai/gpt-oss-20b) drove it autonomously — plain English in, correct live dashboard out, verified against the stored Lens payload and cleaned up — three consecutive runs (16s/9s/7s wall). See docs/e2e-setup.md for the one-time LM Studio setup (permission toggles + API token) and tests/e2e/test_lmstudio.py for the harness. Model note: gpt-oss-20b's parser-enforced tool grammar made it 3/3 reliable; qwen2.5-coder-14b completes the flow too but corrupts its tool-call markers about one run in three.

Related MCP server: Kibana Dashboard Builder

What it does

Lets an LLM work with Kibana through a small, reliable, purpose-built tool surface instead of ~610 raw endpoints — 133 tools grouped into 10 composable toolboxes you enable per deployment. The flagship dashboards toolbox lets a user describe the chart they want, and the server translates a simple declarative spec into real Kibana Lens visualizations and dashboards via the modern Dashboards API (Kibana 9.4+). The other toolboxes cover data management, alerting, cases, security detections, fleet, streams, observability, and platform admin/health.

Design pillars:

• Composable toolboxes — groups of tools enabled/disabled per deployment via configuration; small local models get a small surface, big models can get more.

• Hexagonal core — pure domain logic (spec → Lens translation) isolated from both the MCP adapter and the kibana-py gateway; every layer independently testable.

• Two run modes, one codebase — stdio for a local single user, streamable HTTP in a container for multiple users. Stateless: each request carries the caller's own Kibana API key, so Kibana RBAC and audit logging stay per-user. No multi-tenancy. Exception: saved-objects export handles live in one server-side directory shared by all callers — a handle is a bearer token for that export, and the 20-file retention cap is global, so concurrent HTTP callers can expire each other's handles.

• Tiered write safety — every tool is classified read / write / destructive; deployment config caps the tier, and tools above the cap are never advertised to the model or callable by it (registered like every other tool, then hidden via FastMCP's visibility API — not just denied at call time).

Requirements

• Python 3.12+ (the server itself is pure Python and OS-independent)

• For the dev workflow (Makefile, scripts, local stack): a POSIX shell, GNU make, and Docker with ~5 GB free memory for the Elasticsearch + Kibana stack. Windows: use WSL2.

• A Kibana 9.4+ deployment (or the bundled disposable local stack).

Quick start

New here? The User Guide walks you from zero to your first talked-into-existence dashboard in ~10 minutes, on a disposable local Kibana with sample data.

export KIBANA_URL=https://your-kibana.example.com
export KIBANA_API_KEY=<your Kibana API key>
uvx mcp-for-kibana
# or from a local checkout:
uv run mcp-for-kibana

Runs stdio by default — one process per user, talking to Kibana as that user's own API key. See Configuration for every setting.

Claude Code

claude mcp add kibana --env KIBANA_API_KEY=<your key> -- uv --directory /path/to/checkout run mcp-for-kibana

LM Studio

Add an entry to ~/.lmstudio/mcp.json — see docs/examples/mcp.json for a stdio and an HTTP example. For the full local E2E setup (real model, real Kibana, real dashboard), see docs/e2e-setup.md.

Any other MCP client (streamable HTTP)

Point the client at http://<host>:8000/mcp with header Authorization: ApiKey <your Kibana API key> — see Docker below for running the HTTP server.

Tool reference

133 tools across 10 toolboxes, each tool classified by tier — read / write / destructive (64 / 40 / 29). Enable toolboxes per deployment with KIBANA_MCP_TOOLBOXES; cap the tier with KIBANA_MCP_TIER. A tool above the cap is not merely denied at call time — it never appears in the tool list (registered, then hidden via FastMCP's visibility API).

A tier includes everything below it: read registers only read tools, write (the default) adds write, destructive adds destructive. The default toolbox set is dashboards,data-management (coupled — building a viz needs a data view).

See the full per-tool reference for every tool's arguments and return shape.

Configuration

All settings are read once, in kibana_mcp.config.Settings, and are set via env vars (prefix KIBANA_MCP_ for the deployment-shaped ones; KIBANA_URL, KIBANA_API_KEY, and KIBANA_PUBLIC_URL are recognized both bare and prefixed, matching how Kibana's own tooling names them):

Docker

The container always runs HTTP transport (KIBANA_MCP_TRANSPORT=http is baked into the image), stateless, on port 8000. KIBANA_API_KEY is not needed at the container level: HTTP mode expects each caller to send their own key per request, and by default ignores KIBANA_API_KEY even if it's set (set KIBANA_MCP_ALLOW_ENV_KEY_HTTP=true to opt back into it as a shared fallback):

docker run -p 8000:8000 -e KIBANA_URL=https://your-kibana.example.com \
  ghcr.io/pedro-angel/mcp-for-kibana

curl http://localhost:8000/mcp \
  -H 'Authorization: ApiKey <your Kibana API key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The image runs as a non-root user (mcp-for-kibana, uid 10001).

Development

make setup       # uv sync + git hooks (uv-native path)
make help        # every dev task, self-documented

No uv on the machine? ./bootstrap.sh installs just the git hooks (prek / pre-commit fallback chain).

The engineering conventions this project holds itself to are in CONTRIBUTING.md, and every one of them is enforced by a gate rather than by convention alone — see the Definition-of-Done gate below. Git & CI discipline comes from git-controls-starter.

Test matrix

Six tiers, from fastest/most-isolated to slowest/most-real:

make test              # unit — fakes only, no network; the default selection
make test-contract     # starts + seeds the docker Kibana stack itself, then -m contract
make test-e2e-replay   # replays a RECORDED model turn through a real MCP client
make test-e2e          # a REAL local model in LM Studio — see docs/e2e-setup.md
make streams-ephemeral # destructive streams path on its own throwaway stack
make fleet-ephemeral   # agent lifecycle on a throwaway 2-agent fleet stack

Everything except test-e2e runs in CI. The two ephemeral tiers own their stack's whole lifecycle (up → test → down) because their paths are destructive: they delete every wired stream, or mutate real enrolled agents, so they cannot share the dev stack. They also cannot run beside it — see scripts/fleet_ephemeral.sh for the measured memory headroom.

On the two e2e tiers. They are not redundant, and one is not a substitute for the other:

The replay tier exists because the surface a model actually touches was otherwise certified only on a maintainer's laptop. It replays a turn recorded from a live gpt-oss-20b run — including the three failures that run recovered from — and asserts the tools still exist, that arguments a real model produced still validate against the live input schemas, and that the error guidance survives. That guidance is load-bearing: a model has no other way to learn your data's field names, and degrading "field 'price' does not exist … did you mean 'Carrier'?" to a bare 400 breaks self-correction for every LLM using this server. Four mutation tests confirm the tier fails when each guard is broken.

(Raw commands underneath: uv run pytest [-m contract|-m e2e|-m e2e_replay] — the suites load elastic-start-local/.env.seed + .env.local in-process; the Makefile is a thin facade.)

The docs site is a CI gate too: uv sync --group docs once, then uv run mkdocs build --strict must pass with zero warnings (uv run mkdocs serve to preview locally).

Before claiming a change "done" — and always before a release — run the Definition-of-Done gate, which certifies completion from dod.config instead of letting the author self-certify:

make dod         # GO/NO-GO over all declared criteria (definition-of-done.sh)

Every tier needing infrastructure is excluded from the default selection (addopts in pyproject.toml), so a bare pytest never silently depends on a stack. CI splits accordingly: checks.yml runs the content gates (lint, types, audit, SAST, unit across Python 3.12–3.14, docs, image build+smoke), and integration.yml provisions real stacks for the live tiers and certifies them through this same gate script with per-tier configs in .github/dod/ — so CI verdicts and make dod cannot drift.

make dod needs the dev stack up for contract/e2e/e2e_replay and down for the ephemeral tiers, so a plain run cannot satisfy both halves. To get a one-shot GO, let the gate cycle the stack for you (default-off, so it never touches infrastructure unasked):

scripts/stack.sh up && scripts/stack.sh seed
KIBANA_MCP_DOD_CYCLE_STACK=1 make dod

e2e_green is the one criterion CI cannot certify — it needs a real model. It stays required in dod.config and n/a in every .github/dod tier, so the local gate remains a strict superset of CI rather than CI quietly becoming the definition of done.

License

Apache 2.0