Skip to main content
Glama
byok-observability-mcp

byok-observability-mcp

npm version License: MIT Awesome MCP Servers Node ≥18 alimuratkuslu/byok-observability-mcp MCP server


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.


How it works


Related MCP server: kubernetes-mcp

⚡ Quick Start

Run once, answer a few questions, get a ready-made .mcp.json:

npx byok-observability-mcp --init

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:

claude
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.

{
  "mcpServers": {
    "observability-mcp": {
      "command": "npx",
      "args": ["-y", "byok-observability-mcp"],
      "env": {
        "GRAFANA_URL":    "https://grafana.mycompany.internal",
        "GRAFANA_TOKEN":  "glsa_...",
        "PROMETHEUS_URL": "https://prometheus.mycompany.internal",
        "KAFKA_UI_URL":   "https://kafka-ui.mycompany.internal",
        "DD_API_KEY":     "your-datadog-api-key",
        "DD_APP_KEY":     "your-datadog-app-key"
      }
    }
  }
}

Credentials in git? Use the ${VAR} approach instead — see Configuration → Method B.

Start Claude Code:

claude

Claude Code reads .mcp.json automatically. No claude mcp add, no build step.

Verify by asking Claude:

What observability tools do you have available?

🧩 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.

# Same .mcp.json as above works out of the box
codex

Or add via CLI:

codex mcp add --transport stdio observability-mcp -- npx -y byok-observability-mcp

🔧 Available tools

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.

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

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

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

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.

Toolset

Covers

core

Metrics, dashboards, monitors, infrastructure

apm

APM services, traces, service map

alerting

Monitors, downtimes, alerts

logs

Log search and analytics

incidents

Incident management

ddsql

SQL-style metric queries

security

Cloud security posture

synthetics

Synthetic test results

networks

Network performance monitoring

dbm

Database monitoring

software-delivery

CI/CD pipelines

llm-obs

LLM observability

cases

Case management

feature-flags

Feature flag tracking


🔑 Getting credentials

  1. Open Grafana → Administration → Users and access → Service accounts

  2. Click Add service account → set Role to Viewer → Create

  3. On the service account page → Add service account token → Generate token

  4. Copy the token (starts with glsa_) — you won't see it again

GRAFANA_URL=https://grafana.mycompany.internal
GRAFANA_TOKEN=glsa_xxxxxxxxxxxxxxxx

If your Grafana uses a self-signed certificate:

GRAFANA_VERIFY_SSL=false

If Prometheus has no authentication:

PROMETHEUS_URL=https://prometheus.mycompany.internal

If Prometheus uses basic auth:

PROMETHEUS_URL=https://prometheus.mycompany.internal
PROMETHEUS_USERNAME=your-username
PROMETHEUS_PASSWORD=your-password

If Kafka UI has no authentication:

KAFKA_UI_URL=https://kafka-ui.mycompany.internal

If Kafka UI requires a login:

KAFKA_UI_URL=https://kafka-ui.mycompany.internal
KAFKA_UI_USERNAME=admin
KAFKA_UI_PASSWORD=your-password

API key: Datadog → Organization Settings → API Keys → New Key

Application key: Datadog → Organization Settings → Application Keys → New Key

DD_SITE — match your Datadog login URL:

Login URL

DD_SITE

app.datadoghq.com

datadoghq.com (default)

app.us3.datadoghq.com

us3.datadoghq.com

app.us5.datadoghq.com

us5.datadoghq.com

app.datadoghq.eu

datadoghq.eu

app.ap1.datadoghq.com

ap1.datadoghq.com

DD_API_KEY=your-api-key
DD_APP_KEY=your-application-key
DD_SITE=datadoghq.com
DD_TOOLSETS=core,apm,alerting

⚙️ Configuration

Method A — Values directly in .mcp.json (simplest)

Put credentials directly in .mcp.json. Works everywhere, no extra steps.

Add .mcp.json to your .gitignore if the repo is shared.

Use ${VAR} placeholders in .mcp.json and put real values in .env.

.mcp.json (safe to commit — contains no secrets):

{
  "mcpServers": {
    "observability-mcp": {
      "command": "npx",
      "args": ["-y", "byok-observability-mcp"],
      "env": {
        "GRAFANA_URL":    "${GRAFANA_URL}",
        "GRAFANA_TOKEN":  "${GRAFANA_TOKEN}",
        "PROMETHEUS_URL": "${PROMETHEUS_URL}",
        "KAFKA_UI_URL":   "${KAFKA_UI_URL}",
        "DD_API_KEY":     "${DD_API_KEY}",
        "DD_APP_KEY":     "${DD_APP_KEY}"
      }
    }
  }
}

.env (add to .gitignore):

GRAFANA_URL=https://grafana.mycompany.internal
GRAFANA_TOKEN=glsa_...

Start Claude with the env loaded:

set -a && source .env && set +a && claude

A ready-made helper script is included:

./scripts/run-claude-with-env.sh

A template .mcp.json with all variables is available as .mcp.json.example.

Add to ~/.claude.json:

{
  "mcpServers": {
    "observability-mcp": {
      "command": "npx",
      "args": ["-y", "byok-observability-mcp"],
      "env": {
        "GRAFANA_URL":   "https://grafana.mycompany.internal",
        "GRAFANA_TOKEN": "glsa_..."
      }
    }
  }
}

📋 Environment variables

Variable

Backend

Required

Description

GRAFANA_URL

Grafana

✅

Base URL of your Grafana instance

GRAFANA_TOKEN

Grafana

✅

Service account token (Viewer role)

GRAFANA_VERIFY_SSL

Grafana

Set to false to skip TLS verification

PROMETHEUS_URL

Prometheus

✅

Base URL of your Prometheus instance

PROMETHEUS_USERNAME

Prometheus

Basic auth username

PROMETHEUS_PASSWORD

Prometheus

Basic auth password

KAFKA_UI_URL

Kafka UI

✅

Base URL of your Kafka UI instance

KAFKA_UI_USERNAME

Kafka UI

Login username

KAFKA_UI_PASSWORD

Kafka UI

Login password

DD_API_KEY

Datadog

✅

Datadog API key

DD_APP_KEY

Datadog

✅

Datadog Application key

DD_SITE

Datadog

Datadog site (default: datadoghq.com)

DD_TOOLSETS

Datadog

Tool groups to load (default: core,apm,alerting)

SLACK_WEBHOOK_URL

Reports

✅*

Slack Incoming Webhook URL for scheduled reports

REPORT_BACKENDS

Reports

Comma-separated backends to include in reports (default: all configured)


📊 Scheduled Reports

Send an automated observability digest to Slack on a schedule — no Claude or Codex instance needs to be running.

How it works

cron / launchd
     │  fires every N minutes
     ▼
npx byok-observability-mcp --report
     │
     │  reads env vars, connects directly to backends
     ▼
Grafana · Prometheus · Kafka UI
     │
     │  categorizes findings → P0 / P1 / P2 / P3
     ▼
Slack Incoming Webhook  →  #your-channel

The command collects data, categorizes every finding by severity, formats a Slack message, sends it, and exits. It is completely stateless.

Severity levels

Level

Meaning

Examples

🔴 P0 — KRİTİK

Service down or unreachable

Grafana alert firing (critical), Kafka cluster offline, backend unreachable

🟠 P1 — YÜKSEK

Degraded, action needed soon

Grafana alert firing (non-critical), Kafka consumer lag > 10 000

🟡 P2 — ORTA

Warning, monitor closely

Grafana alert pending, Kafka consumer lag > 1 000

🟢 P3 — BİLGİ

Informational, all normal

Healthy backends, silenced alerts

Setup

Step 1 — Get a Slack Incoming Webhook URL

  1. Go to api.slack.com/apps → Create New App → From scratch

  2. Incoming Webhooks → toggle on → Add New Webhook to Workspace

  3. Pick a channel → Allow → copy the Webhook URL

Step 2 — Set environment variables

export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ

# Optional: restrict which backends are included (default: all configured)
export REPORT_BACKENDS=grafana,prometheus,kafka

Step 3 — Run a one-off report to verify

npx byok-observability-mcp --report

You should see a message in your Slack channel within seconds.

Step 4 — Schedule with cron

Open your crontab:

crontab -e

Add a line. Examples:

# Every hour at minute 0
0 * * * * SLACK_WEBHOOK_URL=https://hooks.slack.com/... GRAFANA_URL=... GRAFANA_TOKEN=... npx byok-observability-mcp --report >> /tmp/obs-report.log 2>&1

# Every 30 minutes
*/30 * * * * SLACK_WEBHOOK_URL=https://hooks.slack.com/... npx byok-observability-mcp --report >> /tmp/obs-report.log 2>&1
TIP

Put all env vars in a.env file and source it inside the cron command to keep the crontab clean:

0 * * * * bash -c 'source /path/to/.env && npx byok-observability-mcp --report' >> /tmp/obs-report.log 2>&1

Alternative: macOS launchd (runs on login, survives reboots)

Create ~/Library/LaunchAgents/com.observability-mcp.report.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.observability-mcp.report</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/npx</string>
    <string>byok-observability-mcp</string>
    <string>--report</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>SLACK_WEBHOOK_URL</key>
    <string>https://hooks.slack.com/services/XXX/YYY/ZZZ</string>
    <key>GRAFANA_URL</key>
    <string>https://grafana.mycompany.internal</string>
    <key>GRAFANA_TOKEN</key>
    <string>glsa_...</string>
  </dict>
  <key>StartInterval</key>
  <integer>3600</integer>
  <key>StandardOutPath</key>
  <string>/tmp/obs-report.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/obs-report.log</string>
</dict>
</plist>

Load it:

launchctl load ~/Library/LaunchAgents/com.observability-mcp.report.plist

To stop: launchctl unload ~/Library/LaunchAgents/com.observability-mcp.report.plist


💬 Example prompts

Single-backend queries

Backend

Try asking Claude...

Grafana

"List all datasources and tell me which ones are Prometheus type."

Grafana

"Search for dashboards related to 'kubernetes' — list names and UIDs."

Grafana

"Query http_requests_total rate over the last hour via the default Prometheus datasource."

Prometheus

"What is the current value of the up metric? Which targets are down?"

Prometheus

"Show CPU usage (node_cpu_seconds_total rate) over the past hour, by instance."

Prometheus

"List all available metrics that start with http_."

Kafka UI

"List all Kafka clusters. Are there any with offline brokers?"

Kafka UI

"Describe the topic 'orders' in cluster 'production' — partitions and replication factor?"

Kafka UI

"Check consumer lag for group 'order-processor'. Which partitions have the highest lag?"

Datadog

"List all Datadog monitors currently in Alert state."

Datadog

"Show APM service performance for the past hour. Which services have the highest error rate?"

Datadog

"Query aws.ec2.cpuutilization for the last 30 minutes. Which hosts are above 80%?"

🛠️ Incident Response (v0.2.0+)

Goal

Try asking Claude...

Health

"Run a health check on all systems."

Alerts

"Are there any firing alerts in Grafana right now?"

Triage

"Show me the alert rules for the 'Production' folder."

Cross-backend queries

Check the health of all configured observability backends and give me a summary.
I'm seeing high error rates. Check Prometheus for http_requests_total with status=500,
then look for related Datadog monitors that might be alerting.

🔒 Security

NOTE

All tools areread-only. No write operations are performed on any backend.

IMPORTANT

Credentials are read from environment variables andnever logged or sent to Anthropic. Tokens are redacted in all error messages.

  • TLS certificate verification is enabled by default

  • The MCP process runs locally — your infrastructure URLs only reach Claude's context window if you type them into the chat

Least-privilege recommendations:

Backend

Recommended role

Grafana

Service account with Viewer role

Prometheus

Network-level read-only access

Kafka UI

Read-only UI user

Datadog

API key + Application key with read scopes


🛠 Development

git clone https://github.com/alimuratkuslu/byok-observability-mcp
cd byok-observability-mcp
npm install
npm run dev          # run with tsx (no build step)
npm run build        # compile to dist/
npm run typecheck    # TypeScript check without emitting

Tested versions

Backend

Tested version

Grafana

v9.x, v10.x, v11.x

Prometheus

v2.x

Kafka UI

provectus/kafka-ui:v0.7.2


License

MIT

Available Tools

23 tools
grafana_get_alert_rulesA

List all configured Grafana alert rules from the provisioning API. Returns rule UID, title, condition, labels, annotations, folder, and rule group. Use this to see what alert rules are defined.

Inputs: no named parameters.

grafana_get_dashboardA

Get full details of a Grafana dashboard including all panels, by its UID. Use grafana_list_dashboards to find the UID.

Inputs: uid (required).

grafana_healthA

Check Grafana connectivity and retrieve version and database status. Use this to verify the Grafana integration is working.

Inputs: no named parameters.

grafana_list_alertsA

List active (or filtered) alerts from Grafana Alertmanager. Supports filtering by state and label selectors. Returns alert name, state, severity, labels, annotations, and start time. Use this to answer 'are there any firing alerts right now?'

Inputs: state, labels.

grafana_list_dashboardsA

List dashboards in Grafana with an optional search query. Returns UID, title, folder, and tags.

Inputs: query.

grafana_list_datasourcesA

List all datasources configured in Grafana (name, type, UID). Use this to find the UID needed for grafana_query_metrics.

Inputs: no named parameters.

grafana_query_metricsA

Execute a PromQL expression via a Grafana Prometheus datasource and return the results. Use grafana_list_datasources first to find the datasource UID.

Inputs: datasource_uid (required), expr (required), from, to, +1 more.

kafka_broker_healthC

Get broker health for a Kafka cluster — broker IDs, hosts, ports, and disk usage.

Inputs: cluster_name (required).

kafka_consumer_group_lagA

Get consumer lag for a specific consumer group — per-partition offset, end offset, and lag. Highlights partitions with non-zero lag.

Inputs: cluster_name (required), group_id (required).

kafka_describe_topicC

Get detailed information about a specific Kafka topic including partition layout, replication, and segment info.

Inputs: cluster_name (required), topic_name (required).

kafka_list_clustersA

List all Kafka clusters configured in Kafka UI. Returns name, status, broker count, topic count, and partition info.

Inputs: no named parameters.

kafka_list_consumer_groupsC

List consumer groups in a Kafka cluster with their state and member count.

Inputs: cluster_name (required), page, per_page.

kafka_list_topicsA

List topics in a Kafka cluster with partition count, replication factor, and under-replicated partition count.

Inputs: cluster_name (required), page, per_page.

obs_health_checkA

Run a health check across all configured observability backends (Grafana, Prometheus, Kafka UI, Datadog) in parallel and return a status summary table. Use this to answer 'are all systems up?'

Inputs: no named parameters.

obs_investigate_incidentA

Meta-tool that performs parallel root cause analysis (RCA) queries across all enabled backends. Automatically checks Grafana for firing alerts, Prometheus for offline endpoints (up==0), and Kafka clusters for offline brokers.

Inputs: no named parameters.

opsgenie_ack_alertC

Acknowledge an open OpsGenie alert to prevent escalations.

Inputs: alert_id (required).

opsgenie_list_alertsC

List currently open OpsGenie alerts. Returns ID, tinyId, message, priority, and acknowledged status.

Inputs: limit.

opsgenie_who_is_on_callB

List current on-call participants for all schedules. Helps you find who to page.

Inputs: no named parameters.

prometheus_healthB

Check Prometheus connectivity. Returns healthy/unhealthy status.

Inputs: no named parameters.

prometheus_list_metricsB

List all available metric names in Prometheus. Useful for discovery when you don't know the exact metric name.

Inputs: no named parameters.

prometheus_metric_metadataA

Get help text, type, and unit for a specific Prometheus metric. Omit metric_name to list all metadata.

Inputs: metric_name.

prometheus_queryA

Execute an instant PromQL query and return the current value(s). Best for checking current state of a metric (e.g. CPU usage right now).

Inputs: query (required), time.

prometheus_query_rangeA

Execute a PromQL range query and return a time series. Use this to see how a metric changed over time.

Inputs: query (required), start, end, step.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools are clearly distinct by backend (Grafana, Kafka, OpsGenie, Prometheus) and action, with minimal overlap. However, some potential confusion exists between grafana_list_alerts (active alerts) and grafana_get_alert_rules (configured rules), and between prometheus_query (instant) and prometheus_query_range (range), though descriptions help clarify.

    Naming Consistency5/5

    Tool names follow a highly consistent backend_action_resource pattern (e.g., grafana_list_dashboards, kafka_describe_topic, prometheus_query_range). All use snake_case, and verbs like 'list', 'get', 'query' are applied predictably across backends, making the set easy to navigate.

    Tool Count3/5

    With 23 tools, the count is on the high side for a single server, potentially overwhelming. However, given the broad observability domain covering multiple backends (Grafana, Kafka, OpsGenie, Prometheus), it's borderline but justifiable as each tool serves a specific purpose.

    Completeness4/5

    The toolset provides comprehensive read/query capabilities across all backends, with good coverage for monitoring, alerting, and incident investigation. Minor gaps include lack of write/update tools (e.g., creating dashboards or alerts) and limited OpsGenie actions beyond listing and acknowledging, but core workflows are well-supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that lets AI assistants interact with the Sentry API to retrieve and analyze error data, manage projects, and monitor application performance.
      11
      12
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that provides safe, read-only access to Kubernetes resources for debugging and inspection. Built with security in mind, it offers comprehensive cluster visibility without modification capabilities.
      45
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with Datadog's monitoring and observability platform through the MCP protocol. Supports incident management, monitor status checks, log searches, metrics queries, APM traces, dashboard access, RUM analytics, host management, and downtime scheduling.
      13
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables querying logs and metrics from Graylog, Prometheus, and InfluxDB 2.x. It provides tools for executing Lucene log searches, PromQL queries, and Flux queries directly within MCP-compatible clients.
      MIT