io.github.mshegolev/kibana-mcp
Kibana/Elasticsearch MCP — log search, aggregations, index discovery, dashboards.
Open source Open in the app JSON README (API)
About
Kibana/Elasticsearch MCP — log search, aggregations, index discovery, dashboards.
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- mshegolev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.1
- Forks
- 1
- Open pull requests
- 1
- Last push
- 2026-08-12T15:37:20Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:51
- Updated
- 2026-08-29 04:00:51
- Origin id
io.github.mshegolev/kibana-mcp
README
# kibana-mcp
<!-- mcp-name: io.github.mshegolev/kibana-mcp -->
[](https://pypi.org/project/kibana-mcp/)
[](https://www.python.org/)
[](LICENSE)
[](https://github.com/mshegolev/kibana-mcp/actions)
MCP server for **Kibana / Elasticsearch** — log search, aggregations, index discovery, and dashboard browsing via Claude and any MCP-compatible agent.
## Why another Kibana MCP?
Existing integrations require a running Kibana instance with browser-level credentials and often wrap the Kibana UI rather than the stable REST APIs. This server:
- Hits **Elasticsearch REST API directly** for log queries (faster, stable across Kibana UI changes)
- Falls back to the **Kibana Console proxy** when no direct ES URL is configured (zero extra firewall rules)
- Supports **ApiKey auth** (best for agents) as well as Basic auth and anonymous access
- Returns both **structured JSON** (`outputSchema`) and **markdown text** so it works with any MCP client
- Is **read-only** — all tools carry `readOnlyHint: true`, no data is modified
## Tools
| Tool | API | Description |
|------|-----|-------------|
| `kibana_list_indices` | `GET ES/_cat/indices` | Discover available indices with health, docs, size |
| `kibana_search_logs` | `POST ES/{index}/_search` | Full-text log search with time range, sort, size |
| `kibana_aggregate_logs` | `POST ES/{index}/_search` | Terms grouping with count/avg/sum/min/max metric |
| `kibana_list_dashboards` | `GET Kibana/api/saved_objects/_find` | List saved dashboards with search + pagination |
| `kibana_get_dashboard` | `GET Kibana/api/saved_objects/dashboard/{id}` | Fetch one dashboard with panel breakdown |
## Installation
```bash
pip install kibana-mcp
```
Or run directly with `uvx`:
```bash
uvx kibana-mcp
```
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `KIBANA_URL` | Yes | Kibana base URL (e.g. `https://kibana.example.com`) |
| `ELASTICSEARCH_URL` | No | Direct ES endpoint. If unset, ES requests go through Kibana Console proxy |
| `KIBANA_API_KEY` | No | ES API key (`ApiKey base64(id:api_key)` format). Recommended for agents |
| `KIBANA_USERNAME` | No | HTTP Basic auth username (used if API key not set) |
| `KIBANA_PASSWORD` | No | HTTP Basic auth password |
| `KIBANA_SSL_VERIFY` | No | `true` (default) or `false` for self-signed certificates |
Auth priority: **ApiKey** > **Basic** > **anonymous**.
Copy `.env.example` to `.env` and fill in your values.
### MCP Client Configuration (Claude Desktop / claude.app)
```json
{
"mcpServers": {
"kibana": {
"command": "uvx",
"args": ["kibana-mcp"],
"env": {
"KIBANA_URL": "https://kibana.example.com",
"KIBANA_API_KEY": "your-api-key-here"
}
}
}
}
```
Or with direct ES access for better performance:
```json
{
"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
```bash
docker run --rm -i \
-e KIBANA_URL=https://kibana.example.com \
-e KIBANA_API_KEY=your-key \
ghcr.io/mshegolev/kibana-mcp
```
## Usage Examples
### Log Search
```
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)`
### Aggregations
```
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")`
### Index Discovery
```
What log indices are available?
```
→ `kibana_list_indices()`
```
Show me all filebeat indices
```
→ `kibana_list_indices(pattern="filebeat-*")`
### Dashboards
```
Find the infrastructure dashboard
```
→ `kibana_list_dashboards(search="infrastructure")`
```
What panels does dashboard X have?
```
→ `kibana_get_dashboard(dashboard_id="<id from list_dashboards>")`
## Performance Characteristics
- **Log search** (`kibana_search_logs`): typically 50-500ms with direct ES URL; add 100-200ms when routing through Kibana Console proxy
- **Aggregations** (`kibana_aggregate_logs`): `size:0` queries — no hits transferred, usually 10-100ms
- **Index listing**: single `_cat/indices` call, O(index_count) response, typically <100ms
- **Dashboard APIs**: Kibana Saved Objects API, typically 50-200ms; latency is Kibana-side, not network
- Set `ELASTICSEARCH_URL` directly if your agent does frequent log searches — eliminates the proxy overhead
## Development
```bash
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
```
## License
MIT — see [LICENSE](LICENSE).