kafka-sentinel-mcp

Give AI agents safe, read-only eyes on your Kafka clusters.

An MCP (Model Context Protocol) server that exposes Kafka cluster health, consumer lag, partition state, and replay-readiness as structured tools — so LLM agents (Claude, or any MCP client) can diagnose streaming incidents without ever being able to break anything.

Built by an engineer who spent a decade running Kafka-based financial messaging at 99.999% availability, and got tired of every "AI + Kafka" demo assuming write access to production.

Why this exists

When a consumer group stalls at 3 a.m., the questions are always the same: Is it lag? A stuck partition? A rebalance storm? An offset reset gone wrong? These are pattern-matching questions — exactly what LLM agents are good at — but no operator will hand an agent admin rights on a production cluster.

kafka-sentinel-mcp draws a hard line: every tool is read-only by design, enforced at the client-config level (no admin operations are even imported). The agent can observe, correlate, and recommend; a human executes.

Tools

Quick start

pip install kafka-sentinel-mcp   # (or: uv tool install)

# Run against your cluster (read-only credentials!)
KAFKA_BOOTSTRAP=localhost:9092 kafka-sentinel-mcp

Add to Claude Desktop / any MCP client:

{
  "mcpServers": {
    "kafka-sentinel": {
      "command": "kafka-sentinel-mcp",
      "env": { "KAFKA_BOOTSTRAP": "broker1:9092,broker2:9092" }
    }
  }
}

Then ask your agent: "Why is the payments-consumer group falling behind, and can we still replay from where it stalled?"

Security posture

• Read-only by construction: no produce, no topic/config mutation, no offset commits, no ACL ops. The mutation APIs are never imported, and a test in CI greps the server source on every run to keep it that way.

• The observer consumer runs with enable.auto.commit=False and never commits — verified against a real broker, not just asserted.

• Supports SASL/SSL; credentials are read from the environment only and never logged.

• Every tool call is logged with its parameters for audit.

• Least privilege: run with a principal that has only Describe on the cluster and topics, and Describe on consumer groups. When an ACL denies an operation the tool returns a structured result rather than a stack trace:

  {
    "error": "permission_denied",
    "operation": "list_consumer_groups",
    "detail": "...",
    "hint": "The Kafka principal in use lacks the AC
  

... View full README on GitHub