mcp-kafka

mcp-kafka

一个面向 Apache Kafka 的 Model Context Protocol 服务。它让支持 MCP 的客户端（Claude Desktop、Claude Code 等）能够监控和管理 Kafka 集群，包括主题、分区、配置和消费者组（包括积压量）；行为完全由标志控制。

默认安全：启动时为只读模式，可限制为允许列表中的主题，保护内部／关键主题不被修改，并通过显式选择启用破坏性操作。

功能

• 监控 — 集群／代理信息、主题元数据和偏移量、消费者组，以及每个分区和总计的消费者积压量。
• 管理 — 创建主题、添加分区、修改主题配置、重置消费者组偏移量；删除主题／消费者组（管理员）。
• 访问模式 — read-only → read-write → admin，分层控制，模式不会暴露高于自身级别的工具。
• 安全标志 — 主题允许列表、受保护／内部主题、删除权限控制、试运行和 JSON 审计日志（见下文）。
• 身份验证 — 明文、TLS 和 SASL（PLAIN / SCRAM-SHA-256 / SCRAM-SHA-512）。

安全模型

事项	标志	默认值	效果
服务可以执行哪些操作？	KAFKA_MODE	read-only	read-only 仅开放监控；read-write 增加管理功能；admin 增加删除功能。高于当前模式的工具绝不会注册。
哪些主题在操作范围内？	KAFKA_TOPIC_ALLOWLIST	（全部）	设置后，将拒绝对其他主题进行操作。
保护内部主题	KAFKA_PROTECT_INTERNAL_TOPICS	true	以 _ 开头的主题可以读取，但绝不会被修改。
保护特定主题	KAFKA_PROTECTED_TOPICS	（无）	额外指定永远只读的主题。
是否允许删除？	KAFKA_ALLOW_DELETE	false	delete_topic / delete_consumer_group 需要启用此项并使用管理员模式。
预览操作而不触及集群	KAFKA_DRY_RUN	false	写入／管理员工具会验证并记录操作意图，然后返回。
审计记录	KAFKA_AUDIT_LOG	true	每次受保护操作都会向 stderr 输出一行 JSON。
交互式确认	（自动）	—	执行破坏性和高影响操作前，会通过 MCP elicitation 提示用户批准；不支持 elicitation 的客户端将改用 *_ALLOW_* 门控。

工具

读取（read-only 及以上）：cluster_info、list_topics、describe_topic、topic_offsets、list_consumer_groups、describe_consumer_group（含积压量）

写入（read-write 及以上）：create_topic、create_partitions、alter_topic_config、reset_consumer_group_offsets

管理员（admin）：delete_topic、delete_consumer_group（两者都需要 KAFKA_ALLOW_DELETE）

快速开始 — 添加到你的 Agent

已发布到 npm，包名为 @dockndevai/mcp-kafka。无需克隆或构建 — MCP 客户端会按需通过 npx 运行它。请从 read-only 模式开始；所有变量请参阅 .env.example，各客户端的完整指南请参阅 docs/CLIENTS.md。

Claude Code（CLI）

claude mcp add kafka -e KAFKA_BROKERS="localhost:9092" -e KAFKA_MODE="read-only" -- npx -y @dockndevai/mcp-kafka

Claude Desktop · Cursor · Windsurf — 在 claude_desktop_config.json、.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json 中使用相同配置块：

{
  "mcpServers": {
    "kafka": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kafka"
      ],
      "env": {
        "KAFKA_BROKERS": "localhost:9092",
        "KAFKA_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — 在 ~/.codex/config.toml 中：

[mcp_servers.kafka]
command = "npx"
args = ["-y", "@dockndevai/mcp-kafka"]
env = { KAFKA_BROKERS = "localhost:9092", KAFKA_MODE = "read-only" }

VS Code（GitHub Copilot，Agent 模式） — 在 .vscode/mcp.json 中：

{
  "servers": {
    "kafka": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kafka"
      ],
      "env": {
        "KAFKA_BROKERS": "localhost:9092",
        "KAFKA_MODE": "read-only"
      }
    }
  }
}

示例提示词

• “目前积压量最大的消费者组有哪些？”
• “描述 orders 主题并显示其偏移量。”
• “创建一个有 6 个分区、保留 7 天的 events 主题。”（需要 read-write）

从源代码运行（开发）

建议使用上方发布的包。从克隆的仓库运行：

npm install
npm run build
node dist/index.js   # with the environment variables set

开发

npm run dev
npm test
npm run typecheck

发布

此服务提供 server.json，用于官方 MCP 注册表，以及 mcpName，用于验证 npm 所有权。有关发布到 npm 并在 MCP 注册表、Smithery、Glama、Cursor 和 PulseMCP 上列出，请参阅 PUBLISHING.md。

许可证

MIT