内容
# kafka-sentinel-mcp
**为 AI 代理提供安全、只读的 Kafka 集群视图。**
一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 服务器，暴露 Kafka 集群健康状况、消费者延迟、分区状态和重放准备情况，以结构化工具的形式 — 使 LLM 代理（Claude 或任何 MCP 客户端）能够诊断流式传输事件，而无需获得任何写入权限。
由一位工程师构建，他曾在一个 Kafka 集群上运行金融消息传递服务，达到了 99.999% 的可用性，并且对每次“AI + Kafka”的演示都假设具有生产环境的写入权限感到厌倦。
## 为什么存在
当消费者组在凌晨 3 点卡住时，问题总是相同的：是延迟？卡住的分区？重新平衡风暴？偏移重置出错？这些是模式匹配问题 — 正是 LLM 代理擅长的 — 但没有操作员会将管理权限交给代理。
`kafka-sentinel-mcp` 划定了一条明确的界限：**每个工具从设计上都是只读的**，在客户端配置级别强制执行（不导入任何管理操作）。代理可以观察、关联和推荐；人类执行。
## 工具
| 工具 | 返回内容 |
|---|---|
| `list_topics` | 所有非内部主题，包括分区数量和复制因子 — 如果不知道主题名称，从这里开始 |
| `list_consumer_groups` | 所有消费者组 ID 及状态 — 如果不知道组名称，从这里开始 |
| `cluster_health` | 代理数量、控制器状态、未复制 / 离线分区数量 |
| `consumer_lag` | 按组、主题、分区划分的延迟，包括已提交与结束偏移量 |
| `topic_audit` | 复制因子、min.insync.replicas、保留时间以及违反耐用性最佳实践的标志配置 |
| `partition_state` | 领导者、ISR 收缩、跨代理的偏差 |
| `replay_readiness` | 对于组 + 主题：最早可用的偏移量与已提交偏移量，即“我们能否重放错过的事件？” |
| `incident_snapshot` | 所有上述内容的单次调用捆绑，带有时间戳 — 设计用于粘贴到事后分析中 |
## 快速开始
```bash
pip install kafka-sentinel-mcp # （或：uv tool install）
# 运行针对您的集群（只读凭证！）
KAFKA_BOOTSTRAP=localhost:9092 kafka-sentinel-mcp
```
添加到 Claude Desktop / 任何 MCP 客户端：
```json
{
"mcpServers": {
"kafka-sentinel": {
"command": "kafka-sentinel-mcp",
"env": { "KAFKA_BOOTSTRAP": "broker1:9092,broker2:9092" }
}
}
}
```
然后询问您的代理： *"为什么 payments-consumer 组落后了，我们能否重放从停滞处开始的事件？"*
## 安全姿态
- 只读：无生产、无主题/配置修改、无偏移量提交、无 ACL 操作。
- 支持 SASL/SSL；凭证仅通过环境变量传递，绝不记录。
- 每个工具调用都记录带有调用者上下文，用于审计。
- 推荐：使用具有 `Describe`/`Read` ACL 的 Kafka 代理运行 — 服务器优雅地降级并报告它看不到的内容。
## 状态
早期。参见 [ROADMAP.md](ROADMAP.md)。问题和 PR 欢迎 — 特别是关于您希望代理在事件期间告诉您的事项的经验故事。
## 许可证
MIT
<!-- mcp-name: io.github.sanjay-amu/kafka-sentinel-mcp -->
