kafka-sentinel-mcp
kafka-sentinel-mcp is a read-only MCP server that gives AI agents safe, structured visibility into Kafka clusters for diagnosing streaming incidents—without any write, produce, config mutation, or admin access.
list_topics: Discover all non-internal topics with partition count and replication factor.list_consumer_groups: List all consumer group IDs and their state.cluster_health: Report broker count, controller status, and under-replicated/offline partition counts.consumer_lag: Show per-group, per-topic, per-partition lag (committed offset = -1 means no stored offset).topic_audit: Audit replication factor,min.insync.replicas, and retention—flagging configs that violate durability best practices.partition_state: Reveal leaders, ISR state, and leader skew across brokers per partition.replay_readiness: Check whether earliest available offsets still cover the gap since committed offsets, or if retention has deleted the data.incident_snapshot: Return a single timestamped bundle of health + lag + audit + partition state + replay readiness, ideal for postmortems.
All tools are strictly read-only by construction, return structured results on ACL failures (never stack traces), support SASL/SSL, log every call, and never log credentials.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kafka-sentinel-mcp Check consumer lag for payments group"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: mcp-kafka-observer
Tools
Tool | What it returns |
| All non-internal topics with partition count and replication factor — start here if you don't know a topic name |
| All consumer group IDs with state — start here if you don't know a group name |
| Broker count, controller status, under-replicated / offline partition counts |
| Per-group, per-topic, per-partition lag with committed vs end offsets |
| Replication factor, min.insync.replicas, retention, and flags configs that violate durability best practice |
| Leaders, ISR shrinkage, skew across brokers |
| For a group + topic: earliest available offsets vs committed, i.e., "can we still replay what we missed?" |
| One-call bundle of all the above, timestamped — designed for pasting into a postmortem |
Quick start
pip install kafka-sentinel-mcp # (or: uv tool install)
# Run against your cluster (read-only credentials!)
KAFKA_BOOTSTRAP=localhost:9092 kafka-sentinel-mcpAdd 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=Falseand 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
Describeon the cluster and topics, andDescribeon 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 ACL required for this operation. ..." }The agent can then tell the operator which ACL is missing instead of appearing broken. Non-authorization failures are deliberately not swallowed — they propagate, because silently degrading on an unrelated error would hide real problems.
Testing
pip install -e ".[dev]"
pytest -m "not integration" # fast, fully mocked — no Docker needed
pytest -m integration # starts a real Kafka via testcontainers (needs Docker)
pytest # bothThe unit suite mocks librdkafka entirely and covers tool logic. The integration suite starts an actual broker, produces real records, and asserts the tools return correct lag, ISR state, durability flags, and replay-readiness — including that the observer leaves no committed offsets behind. Both run in CI.
Status
Early but tested. See ROADMAP.md. Issues and PRs welcome — especially war stories about what you wish an agent could have told you during an incident.
Citing this work
If you reference this project in academic work, see CITATION.cff, or use the "Cite this repository" button on GitHub.
License
MIT
Available Tools
8 toolscluster_healthB
Broker count, controller, and under-replicated / offline partition summary.
Inputs: no named parameters. Returns: result
consumer_lagB
Per-partition lag for a consumer group on a topic: committed offset vs log-end offset. committed = -1 means no offset stored.
Inputs: group (required), topic (required). Returns: result
incident_snapshotA
One-call bundle: cluster health + lag + audit + partition state + replay readiness. Timestamped for postmortems.
Inputs: group (required), topic (required).
list_consumer_groupsA
List all consumer group IDs on the cluster with their state. Use this first if you don't already know a group name.
Inputs: no named parameters. Returns: result
list_topicsA
List all non-internal topics with partition count and replication factor. Use this first if you don't already know a topic name — every other tool needs one.
Inputs: no named parameters. Returns: result
partition_stateC
Leader/ISR state per partition, plus leader skew across brokers.
Inputs: topic (required). Returns: result
replay_readinessC
Can this group still replay everything since its committed offsets, or has retention already deleted part of the gap?
Inputs: group (required), topic (required). Returns: result
topic_auditA
Replication and durability config audit for a topic. Flags settings that violate mission-critical best practice.
Inputs: topic (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools target clearly distinct concerns: health, lag, audit, partition state, replay readiness. However, cluster_health and incident_snapshot overlap in scope since the snapshot bundles the health data, and topic_audit vs partition_state both touch replication/durability concerns at the partition level, creating minor confusion.
Tool names use a consistent noun-based pattern (adjective_noun) like cluster_health, consumer_lag, topic_audit, partition_state — not strictly verb_noun but internally consistent. Minor deviation is having two 'list_' verbs mixed in with the descriptive noun pattern, though this reads as intentional since they are discovery operations.
Eight tools for a Kafka operational monitoring server is a reasonable, focused scope. Each tool maps to a distinct operational concern with no obvious redundancy, and the incident_snapshot aggregation is a valuable convenience rather than bloat.
The surface covers the core read-only operational concerns an agent would need: discovery (list_topics, list_consumer_groups), health, lag, audit, partition state, and replay/retention analysis. Minor gaps exist — there's no consumer group reset or topic config mutation (read-only by design), and no offset trimming tool, but for an operational sentinel these are reasonable absences.
Maintenance
Related MCP Connectors
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Read-only health context MCP server for Iris users.
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server for Apache Kafka that allows LLM agents to inspect topics, consumer groups, and safely manage offsets (reset, rewind).1914Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents real-time observability into Apache Kafka clusters, enabling natural language queries for broker health, consumer lag, and diagnostics.MIT
- FlicenseAqualityDmaintenanceRead-only MCP server that exposes Kubernetes platform state (tenants, pods, SLOs, ArgoCD applications, chaos schedules, and catalog services) to AI agents, enabling natural language queries about cluster health and configuration.6-

Conduktor MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceEnables Claude, Cursor, or any MCP-compatible client to query Apache Kafka topics, consumer groups, schemas, and cluster health in natural language, served from your own self-hosted instance. Access is read-only and inherits the token holder's existing RBAC, so only metadata reaches the model unless a capped message-reading tool is explicitly used.48 npm5Apache 2.0