Kafka MCP CLI

kafka-mcp 是一个基于 TypeScript 开发的 Kafka 查询 CLI，同时配套了一份可供 AI Agent 使用的 Skill 定义。

当前支持的能力包括：

• 从配置文件或环境变量读取 Kafka 地址并建立连接
• 获取 Topic 列表并支持搜索
• 获取指定 Topic 的消息并支持搜索
• 获取消费者组列表
• 查看指定消费者组在某个 Topic 上的消费进度
• 通过命令写入和查看 ~/.config/kafka-mcp/config.json
• 安装面向 Cursor、Claude、Codex 的技能模板

功能与命令

当前 CLI 提供以下 8 个命令：

1. config

管理用户配置文件，配置会写入：

~/.config/kafka-mcp/config.json

常用子命令：

• config path：查看配置文件路径
• config show：查看当前用户配置
• config set：写入配置

示例：

npx kafka-mcp config path
npx kafka-mcp config show
npx kafka-mcp config set --brokers localhost:9092 --client-id kafka-mcp-cli
npx kafka-mcp config set --brokers localhost:9092,localhost:9093 --ssl
npx kafka-mcp config set --brokers localhost:9092 --sasl-mechanism plain --sasl-username demo --sasl-password secret

2. topics

列出所有 Topic，并支持按名称搜索。

示例：

npx kafka-mcp topics
npx kafka-mcp topics --search order

3. topic

查看某个 Topic 的元数据，包括：

• 分区编号
• leader
• replicas
• ISR

示例：

npx kafka-mcp topic --topic orders

4. messages

读取指定 Topic 的消息，并支持按关键字搜索。

搜索范围包括：

• Topic 名称
• Message Key
• Message Value
• Message Headers

常用参数：

• --topic：指定 Topic
• --search：搜索关键字
• --limit：最多返回多少条匹配消息，默认 10
• --timeout-ms：读取超时时间，默认 5000
• --latest：从最新 offset 开始读取，默认从最早 offset 开始

示例：

npx kafka-mcp messages --topic orders
npx kafka-mcp messages --topic orders --search paid --limit 20
npx kafka-mcp messages --topic orders --latest

5. groups

列出消费者组，并支持按组名搜索。

示例：

npx kafka-mcp groups
npx kafka-mcp groups --search billing

6. group describe

一次性查看某个消费者组的完整信息，包括：

• group 基本信息
• state
• protocol / protocolType
• 成员列表
• 每个成员负责的 topic / partition
• 该 group 涉及的所有 topic 的 committed offset / latest offset / lag

示例：

npx kafka-mcp group describe --group billing-consumers

7. group-progress

查看某个消费者组在某个 Topic 上的消费进度。

输出内容包括：

• 分区编号
• 当前负责该分区的消费者成员
• 已提交 offset
• Topic 最新 offset
• Lag

示例：

npx kafka-mcp group-progress --group billing-consumers --topic orders

8. skill-install

安装可复用的技能模板，支持：

• cursor
• claude
• codex

默认安装位置：

• cursor：当前目录下的 .cursor/rules/kafka-mcp.mdc
• claude：当前目录下的 .claude/commands/kafka-mcp.md
• codex：$CODEX_HOME/skills/kafka-cli-inspector/SKILL.md

常用参数：

• --dir：指定安装根目录
• --force：覆盖已有文件

示例：

npx kafka-mcp skill-install cursor
npx kafka-mcp skill-install claude
npx kafka-mcp skill-install codex
npx kafka-mcp skill-install cursor --dir /path/to/project --force

配置方式

CLI 会按以下顺序读取配置，找到第一个存在的配置源后使用：

1. 当前目录下的 .kafka-mcp.json
2. ~/.config/kafka-mcp/config.json
3. 环境变量会覆盖上述配置

推荐直接使用命令写入用户配置：

npx kafka-mcp config set --brokers localhost:9092 --client-id kafka-mcp-cli

最小配置示例：

{
  "brokers": ["localhost:9092"],
  "clientId": "kafka-mcp-cli",
  "ssl": false
}

如果 Kafka 开启了 SASL，也可以在配置文件中增加认证信息：

{
  "brokers": ["localhost:9092"],
  "clientId": "kafka-mcp-cli",
  "sasl": {
    "mechanism": "plain",
    "username": "username",
    "password": "password"
  }
}

支持的环境变量：

• KAFKA_BROKERS
• KAFKA_CLIENT_ID
• KAFKA_SSL
• KAFKA_SASL_MECHANISM
• KAFKA_SASL_USERNAME
• KAFKA_SASL_PASSWORD

安装

本地开发：

npm install
npm run build

如果要直接使用已经发布到 npm 的版本，可以有两种方式。

方式一：全局安装

npm install -g kafka-mcp

安装完成后可以直接执行：

kafka-mcp --help
kafka-mcp topics
kafka-mcp messages --topic orders --search paid

方式二：使用 npx 直接运行，无需全局安装

npx kafka-mcp --help
npx kafka-mcp topics
npx kafka-mcp messages --topic orders --search paid

如果你想固定版本，也可以这样使用：

npx [email protected] --help

使用示例

npx kafka-mcp topics --search order
npx kafka-mcp topic --topic orders
npx kafka-mcp messages --topic orders --search paid --limit 20
npx kafka-mcp groups --search billing
npx kafka-mcp group describe --group billing-consumers
npx kafka-mcp group-progress --group billing-consumers --topic orders
npx kafka-mcp config show
npx kafka-mcp skill-install cursor

如果使用已发布的 npm 包，对应命令可以写成：

kafka-mcp topics --search order
kafka-mcp topic --topic orders
kafka-mcp messages --topic orders --search paid --limit 20
kafka-mcp groups --search billing
kafka-mcp group describe --group billing-consumers
kafka-mcp group-progress --group billing-consumers --topic orders
kafka-mcp config show
kafka-mcp skill-install cursor
kafka-mcp skill-install claude
kafka-mcp skill-install codex

Skill

可复用的 Skill 定义位于 skills/kafka-cli/SKILL.md，后续可以基于这个 CLI 继续扩展成面向 Codex、Claude 或其他 Agent 的 Kafka 操作能力。