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

Tool	What it returns
`list_topics`	All non-internal topics with partition count and replication factor — start here if you don't know a topic name
`list_consumer_groups`	All consumer group IDs with state — start here if you don't know a group name
`cluster_health`	Broker count, controller status, under-replicated / offline partition counts
`consumer_lag`	Per-group, per-topic, per-partition lag with committed vs end offsets
`topic_audit`	Replication factor, min.insync.replicas, retention, and flags configs that violate durability best practice
`partition_state`	Leaders, ISR shrinkage, skew across brokers
`replay_readiness`	For a group + topic: earliest available offsets vs committed, i.e., "can we still replay what we missed?"
`incident_snapshot`	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-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: no produce, no topic/config mutation, no offset commits, no ACL ops.
Supports SASL/SSL; credentials via env only, never logged.
Every tool call is logged with caller context for audit.
Recommended: run with a Kafka principal that has Describe/Read ACLs only — the server degrades gracefully and reports what it can't see.

Status

Early. See ROADMAP.md. Issues and PRs welcome — especially war stories about what you wish an agent could have told you during an incident.

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kafka_sentinel_mcp-0.1.2.tar.gz (85.5 kB view details)

Uploaded Jul 23, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

kafka_sentinel_mcp-0.1.2-py3-none-any.whl (7.5 kB view details)

Uploaded Jul 23, 2026 Python 3

File details

Details for the file kafka_sentinel_mcp-0.1.2.tar.gz.

File metadata

Download URL: kafka_sentinel_mcp-0.1.2.tar.gz
Upload date: Jul 23, 2026
Size: 85.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for kafka_sentinel_mcp-0.1.2.tar.gz
Algorithm	Hash digest
SHA256	`bd1747b277e62f0756141bf8f094ca4f682ef0b1acf0d95a52aebf569cd571e8`
MD5	`4727aa526a57174cbe5dc9e980ae8c68`
BLAKE2b-256	`8999a7aff10de2134386a0438a69554f5e5cdd82494589b398c547002f7bea49`

See more details on using hashes here.

Provenance

The following attestation bundles were made for kafka_sentinel_mcp-0.1.2.tar.gz:

Publisher: publish.yml on sanjay-amu/kafka-sentinel-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: kafka_sentinel_mcp-0.1.2.tar.gz
- Subject digest: bd1747b277e62f0756141bf8f094ca4f682ef0b1acf0d95a52aebf569cd571e8
- Sigstore transparency entry: 2229178378
- Sigstore integration time: Jul 23, 2026
Source repository:
- Permalink: sanjay-amu/kafka-sentinel-mcp@a3f1562178f16341a029c47b81dc2cbe42a9947b
- Branch / Tag: refs/tags/v0.1.2
- Owner: https://github.com/sanjay-amu
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@a3f1562178f16341a029c47b81dc2cbe42a9947b
- Trigger Event: release