☸️ K8s Observability MCP

Small MCP server that lets you explore Kubernetes metrics, logs, traces, and service graph data via simple tools.

• 🐍 Python 3.13

• 📈 Prometheus

• 🔎 Jaeger

• 🕸️ Neo4j

• ☸️ Kubernetes API

Features

• 📊 Get pod/service metrics (instant and range)

• 📜 Read pod/service logs with important-line filtering

• 🔗 Service map from Neo4j (uses/depends)

• 🧭 Cluster overview (pods and services)

• 🧵 Trace summaries and details from Jaeger

Related MCP server: OpenTelemetry MCP Server

Requirements

• 🐍 Python 3.13+

• 📦 Poetry

• ☸️ Access to your cluster (kubeconfig on this machine)

• 📈 Prometheus URL

• 🔎 Jaeger URL

• 🕸️ Neo4j URI, user, password

Setup

• Install (Poetry)

poetry install

• Configure env

cp .env.example .env
# edit .env with your values

Run

poetry run python mcp_server.py

Then connect with your MCP client to use the tools.

Tools

🔍 Kubernetes Resource Inspection

• get_pods_from_service(service)

  • Returns all pods belonging to a specific service

  • Shows pod names and current status (Running, Pending, etc.)

• get_cluster_pods_and_services()

  • Comprehensive cluster overview

  • Lists all pods and services with counts

📊 Metrics & Observability

• get_metrics(resource_name, resource_type)

  • Retrieves instant Prometheus metrics for a pod or service

  • Parameters:

    • resource_name: The exact name of the Kubernetes resource

    • resource_type: Either "pod" or "service"

  • Returns CPU, memory, network, thread, and container specifications

• get_metrics_range(resource_name, resource_type, time_range_minutes)

  • Historical metrics over a specified time range from Prometheus

  • Parameters:

    • resource_name: The exact name of the Kubernetes resource

    • resource_type: Either "pod" or "service"

    • time_range_minutes: Historical lookback in minutes (minimum 1)

• get_logs(resource_name, resource_type, tail=100, important=True)

  • Retrieve pod/service logs with optional keyword filtering

  • Parameters:

    • resource_name: The exact name of the Kubernetes resource

    • resource_type: Either "pod" or "service"

    • tail: Number of recent log lines to retrieve (default: 100)

    • important: If true, filter for ERROR, WARN, CRITICAL keywords (default: true)

🔗 Service Dependencies & Graph

• get_services_used_by(service)

  • Returns downstream services called by the given service

  • Shows service dependency chain (who calls whom)

• get_dependencies(service)

  • Retrieves infrastructure dependencies for a service

  • Includes databases, caches, message queues, etc.

🧵 Distributed Tracing

• get_traces(service_name, only_errors=False)

  • Retrieves traces for a specific service from Jaeger

  • Parameters:

    • service_name: The name of the service to retrieve traces for

    • only_errors: If true, return only traces containing errors (default: false)

  • Returns: traceID, latency_ms, has_error, service sequence

• get_trace(trace_id)

  • Retrieves detailed information for a specific trace by ID

  • Parameters:

    • trace_id: The unique trace ID to retrieve

  • Includes all spans with timestamps, durations, tags, and errors

Notes

• Uses your default kubeconfig. Set TARGET_NAMESPACE in .env to scope queries.

• 🕸️ Service graph docs: see service-graph/README.md for how the Neo4j service graph is built (Jaeger CALLS + static USES), how to load it, and the result image.