alimuratkuslu/byok-observability-mcp

Query your observability stack from Claude Code, Codex, or any MCP client and no data leaves your machine.
---
**Bring Your Own Keys** — credentials stay in env vars on your machine. No clone, no build, runs via npx.
**Partial setup** — configure only the backends you use. Tools for unconfigured backends are never exposed.
Quick Start ·
Tools ·
Credentials ·
Configuration ·
Scheduled Reports ·
Examples ·
Security ·
Development
---
How it works
🤖 Claude Code / Codex CLI
│
▼
⚡ byok-observability-mcp
(Local npx process)
│
🔒 env vars never leave your machine
│
▼
┌─────────────────────────────────┐
│ 📊 Grafana 🔥 Prometheus │
│ 🛶 Kafka UI 🐶 Datadog │
└─────────────────────────────────┘
---
⚡ Quick Start
Option A — Interactive wizard (recommended)
Run once, answer a few questions, get a ready-made .mcp.json:
The wizard will:
- Let you pick which backends to configure
- Ask for credentials per service
- Test connectivity with your real endpoints before writing anything
- Write .mcp.json to your project root or ~/.claude/ — your choice
Then just start Claude Code:
> [!TIP]
> **That's it.** No clone, no build, no env file. Works in under 60 seconds.
---
Option B — Manual .mcp.json
Create .mcp.json in your project root. Include **only** the backends you need.
> **Credentials in git?** Use the ${VAR} approach instead — see Configuration → Method B.
Start Claude Code:
Claude Code reads .mcp.json automatically. No claude mcp add, no build step.
Verify by asking Claude:
---
🧩 Supported clients
| Client | Configuration |
|--------|--------------|
| **Claude Code** | .mcp.json in project root (recommended) or claude mcp add CLI |
| **OpenAI Codex CLI** | .mcp.json in project root — same format as Claude Code |
Both clients read .mcp.json automatically. The Quick Start above works for either.
Codex CLI example
Or add via CLI:
---
🔧 Available tools
🛰️ System — 1 tool
> Always available. Checks connectivity across all configured backends.
| Tool | Description |
|------|-------------|
| obs_health_check | **Unified Health Check.** Runs a parallel check on all backends and returns a status table. |
  7 tools
> Enabled when GRAFANA_URL + GRAFANA_TOKEN are set.
| Tool | Description |
|------|-------------|
| grafana_health | Check connectivity, version, and database status |
| grafana_list_datasources | List all datasources (name, type, UID) |
| grafana_query_metrics | Run a PromQL expression via a Grafana datasource |
| grafana_list_dashboards | Search and list dashboards by name or tag |
| grafana_get_dashboard | Get panels and metadata for a dashboard by UID |
| grafana_list_alerts | List active alerts from Alertmanager (firing/pending) |
| grafana_get_alert_rules | List all configured alert rules across all folders |
  5 tools
> Enabled when PROMETHEUS_URL is set.
| Tool | Description |
|------|-------------|
| prometheus_health | Check connectivity |
| prometheus_query | Instant PromQL query — current value of a metric |
| prometheus_query_range | Range PromQL query — metric values over time |
| prometheus_list_metrics | List all available metric names |
| prometheus_metric_metadata | Get help text and type for a specific metric |
  6 tools
> Enabled when KAFKA_UI_URL is set.
| Tool | Description |
|------|-------------|
| kafka_list_clusters | List configured Kafka clusters and their status |
| kafka_list_topics | List topics in a cluster |
| kafka_describe_topic | Get partition count, replication factor, and config |
| kafka_list_consumer_groups | List consumer groups and their state |
| kafka_consumer_group_lag | Get per-partition lag for a consumer group |
| kafka_broker_health | Broker count and disk usage per broker |
  proxied via official server
> Enabled when both DD_API_KEY and DD_APP_KEY are set. Proxies the official Datadog MCP server.
Default toolsets: core, apm, alerting. Set DD_TOOLSETS=all to load everything.