Kafka管理工具

一个基于Spring Boot和Spring AI MCP的Kafka管理工具集,提供主题管理、消息生产消费、消费者组监控等功能。

  • by arabaaoui
  • Java
  • 本地部署
  • 更新于
在 GitHub 查看 arabaaoui/kafka-mcp-server

使用说明

🛠️ 可用的MCP工具

总计:22个工具 分为7类

📁 主题(4个工具)

工具 描述 参数
listTopics 列出所有主题 -
describeTopic 描述一个特定话题 topic (字符串)
createTopic 创建一个新主题 topic, partitions, replicationFactor
deleteTopic 删除主题 topic (字符串)

💬 消息(2个工具)

工具 描述 参数
consumeMessages 从主题中消费消息 topic, maxMessages?, timeout?
produceMessage 向主题发送消息 topic, key?, value

👥 消费者群体(2个工具)

工具 描述 参数
listConsumerGroups 列出所有消费者组 -
describeConsumerGroup 描述一个消费者组 group (字符串)

📊 集群监控(5种工具)

工具 描述 参数
getClusterInfo 集群信息(代理服务器,控制器) -
describeBroker 配置代理服务器 brokerId (数字)
getClusterMetrics 集群健康指标 -
analyzeTopicPartitions 带偏移量的分区分析 topic (字符串)
checkClusterHealth 完整诊断及建议 -

🔍 集群模式与平台(1个工具)🆕

工具 描述 参数
detectClusterMode 检测KRaft/Zookeeper + 平台(Strimzi/Confluent/Apache/MSK) -

📈 Prometheus 指标(2个工具)🆕

工具 描述 参数
getPrometheusMetrics 从Prometheus获取Kafka指标 -
getBrokerPrometheusMetrics 代理指标(吞吐量、CPU、RAM) brokerId (数字)

📋 模式注册表(8个工具)🆕

工具 描述 参数
getSchemaRegistryInfo Schema Registry 信息 -
listSchemaSubjects 列出所有主题 -
getSchemaDetails 图案的详细信息 subject, version?
listSchemaVersions 主题的所有版本 subject
registerSchema 记录新方案 subject, schema, schemaType?
checkSchemaCompatibility 检查兼容性 subject, schema, version?
deleteSchemaVersion 删除版本 subject, version
deleteSchemaSubject 删除整个主题 subject

⚠️ 常见错误:“JSON输入意外结束”

症状 :

SyntaxError: Unexpected token '.', "  .   ____  "... is not valid JSON

原因 Spring Boot 的横幅或日志会污染标准输出。

解决方案 ✅ 已在此项目中通过以下方式修正:

  • spring.main.banner-mode: off 在`application# Kafka MCP Server v2.0 - Spring Boot 版本中

一个用于Kafka的现代MCP(模型上下文协议)服务器,开发采用 Spring Boot 3.2 和 Spring AI MCP(注:MCP在此处可能是一个特定上下文或项目中的缩写,没有直接的中文对应,因此保持原样).

🚀 版本2.0新特性

  • ✅(对号,表示正确、确认或完成) Spring Boot 3.2 - 现代且高性能的架构
  • ✅ Spring AI MCP(注:此处“MCP”可能是一个特定上下文中的缩写或术语,没有具体上下文难以给出确切翻译,但一般可理解为“Machine Learning/Model Configuration Pipeline”等类似含义的缩写,具体需根据上下文确定。若“MCP”在此处为专有名词或特定项目名,则应保留原样或根据官方翻译进行调整。) - 注释 @Tool 以实现原生集成
  • ✅ 自动配置 - 通过简化配置 application.yml
  • ✅ 类型安全的DTO(数据传输对象) - 使用Lombok进行结构化响应
  • ✅ 高级日志记录 - 操作的全程可追溯性
  • ✅(这个符号在中文中通常表示“正确”、“对”或“确认”的意思,但直接翻译时没有对应的中文文字,因此保留原符号或根据上下文解释其含义) 优化后的容器 - 多阶段构建以实现轻量级Docker

📋 先决条件

  • Java 17及以上版本 (用于地方发展)
  • Maven 3.9+ (用于本地构建)
  • Docker (用于容器化部署)
  • 网络访问 在Kafka/Strimzi集群上

🏗️ 项目架构

文件夹结构

kafka-mcp-server/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── carrefour/
│   │   │           └── kafka/
│   │   │               └── mcp/
│   │   │                   ├── KafkaMcpServerApplication.java  # Point d'entrée Spring Boot
│   │   │                   ├── config/
│   │   │                   │   └── KafkaConfig.java           # Configuration Kafka (Admin, Producer, Consumer)
│   │   │                   ├── tools/
│   │   │                   │   └── KafkaMcpTools.java         # Services MCP avec @Tool annotations
│   │   │                   └── dto/
│   │   │                       └── *.java                     # DTOs pour les réponses (Lombok)
│   │   └── resources/
│   │       └── application.yml                                # Configuration Spring Boot
│   └── test/
│       └── java/
│           └── com/carrefour/kafka/mcp/
│               └── KafkaMcpToolsTest.java                     # Tests unitaires
├── Dockerfile                                                 # Multi-stage Docker build
├── pom.xml                                                    # Dépendances Maven
├── docker-compose.yml                                         # Configuration Docker Compose
└── README.md

分层架构

┌─────────────────────────────────────────┐
│         Claude Desktop / API            │
│      (Client MCP via stdio)             │
└────────────────┬────────────────────────┘
                 │ JSON-RPC over stdio
                 ▼
┌─────────────────────────────────────────┐
│       Spring AI MCP Framework           │
│  - Protocol handling (initialize, etc)  │
│  - Tool discovery & invocation          │
│  - JSON serialization                   │
└────────────────┬────────────────────────┘
                 │ @Tool methods
                 ▼
┌─────────────────────────────────────────┐
│         KafkaMcpTools Service           │
│  @Tool kafka_list_topics()              │
│  @Tool kafka_describe_topic()           │
│  @Tool kafka_create_topic()             │
│  @Tool kafka_consume_messages()         │
│  @Tool kafka_produce_message()          │
│  etc...                                 │
└────────────────┬────────────────────────┘
                 │ Uses
                 ▼
┌─────────────────────────────────────────┐
│     Spring Kafka Components             │
│  - KafkaAdmin (topic management)        │
│  - KafkaTemplate (producing)            │
│  - KafkaConsumer (consuming)            │
│  - AdminClient (admin operations)       │
└────────────────┬────────────────────────┘
                 │ Kafka Protocol
                 ▼
┌─────────────────────────────────────────┐
│      Kafka/Strimzi Cluster              │
│  bootstrap.dev.kafkahub...9431          │
└─────────────────────────────────────────┘

🔧 主要部件

1. KafkaMcpServer应用程序

使用注解的Spring Boot入口点:

  • @SpringBootApplication - 自动配置
  • @EnableKafka - 启用Kafka支持

2. Kafka配置(KafkaConfig)

集中式Kafka配置:

  • KafkaAdmin(可译为“Kafka管理器”或保持原样,具体取决于上下文是否需要更具体的翻译) 管理操作(创建/删除主题,描述组)
  • 生产者工厂 消息生产者的工厂
  • 消费者工厂 消息消费者工厂
  • KafkaTemplate 简化生产的Spring模板
  • 支持 SASL/SSL(简单认证安全层/安全套接字层) 通过属性进行安全配置

3. KafkaMcpTools(可译为“Kafka MCP工具”或根据具体上下文调整为更贴切的表述,如“Kafka多组件处理工具”等,但“KafkaMcpTools”本身作为专有名词或工具名称,直接保留原样在中文中也是可接受的)

带有注释的主要服务 @Tool Spring AI:

@Tool(name = "kafka_list_topics",
        description = "Liste tous les topics Kafka disponibles")
public TopicListResponse listTopics() { ... }

@Tool(name = "kafka_consume_messages",
        description = "Consomme des messages d'un topic")
public MessageListResponse consumeMessages(
@ToolParameter(description = "Nom du topic", required = true) String topic,
@ToolParameter(description = "Max messages", required = false) Integer maxMessages
        ) { ... }

特点 :

  • 通过自动注入依赖项 @RequiredArgsConstructor
  • 使用SLF4J进行详细日志记录
  • 使用try-catch实现强大的错误处理
  • 结构化DTO的返回

4. DTOs(数据传输对象)

使用Lombok创建不可变类:

  • @Data - 自动的getter/setter方法
  • @Builder - 流畅的模式构建器
  • @NoArgsConstructor / @AllArgsConstructor - 建筑商

示例:

  • TopicListResponse - 主题列表
  • MessageInfo - 消息详情
  • ConsumerGroupDescriptionResponse - 消费者组的状态

🚀 安装与构建

⚠️ 重要提示 - MCP 协议和 stdout

MCP协议使用 仅用于JSON-RPC的标准输出所有日志都应发送至 标准错误输出(stderr)。

✅ 已在项目中配置 :

  • Banner Spring Boot 已禁用(banner-mode: off)
  • 日志重定向到 stderr 通过 logback-spring.xml
  • 没有在标准输出(stdout)上显示控制台输出

选项1:使用Docker构建(推荐)

# Clone le repository
git clone <your-repo>
cd kafka-mcp-server

# Build l'image Docker
docker build -t kafka-mcp-server:2.0.0 .

# L'image finale fait ~150MB (optimisée avec Alpine)

选项2:构建测试

# Exécuter le script de test (Linux/Mac)
chmod +x test-mcp-server.sh
./test-mcp-server.sh

# Le script vérifie:
# ✅ stdout contient uniquement du JSON
# ✅ 8 outils MCP sont exposés
# ✅ Connexion Kafka fonctionne

选项3:使用Maven构建

# Build le projet
mvn clean package

# Le JAR sera dans target/kafka-mcp-server-2.0.0.jar
java -jar target/kafka-mcp-server-2.0.0.jar

选项4:地方发展

# Avec Maven Wrapper
./mvnw spring-boot:run

# Ou avec Maven installé
mvn spring-boot:run

📦 配置

环境变量

变量 描述 默认值 必填
KAFKA_BOOTSTRAP_SERVERS Kafka 代理的地址 localhost:9092 ✅
KAFKA_SECURITY_PROTOCOL 安全协议 PLAINTEXT ❌
KAFKA_SASL_MECHANISM SASL 机制 - ❌
KAFKA_SASL_JAAS_CONFIG JAAS 配置 - ❌

application.yml

kafka:
  bootstrap-servers: ${KAFKA_BOOTSTRAP_SERVERS}
  security-protocol: ${KAFKA_SECURITY_PROTOCOL:PLAINTEXT}
  sasl-mechanism: ${KAFKA_SASL_MECHANISM:}
  sasl-jaas-config: ${KAFKA_SASL_JAAS_CONFIG:}

spring:
  ai:
    mcp:
      server:
        enabled: true
        transport: stdio
        name: kafka-carrefour

🎯 使用

1. 使用Docker启动

基本配置(PLAINTEXT)

docker run -i --rm \
  -e KAFKA_BOOTSTRAP_SERVERS=bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431 \
  kafka-mcp-server:2.0.0

使用SASL/SSL的配置

docker run -i --rm \
  -e KAFKA_BOOTSTRAP_SERVERS=broker.prod.kafka.com:9093 \
  -e KAFKA_SECURITY_PROTOCOL=SASL_SSL \
  -e KAFKA_SASL_MECHANISM=SCRAM-SHA-512 \
  -e KAFKA_SASL_JAAS_CONFIG='org.apache.kafka.common.security.scram.ScramLoginModule required username="user" password="pass";' \
  kafka-mcp-server:2.0.0

2. 配置Claude桌面版

编辑 ~/.config/Claude/claude_desktop_config.json (Linux/Mac) 或者 %APPDATA%\Claude\claude_desktop_config.json (Windows):

Linux/Mac 配置

{
  "mcpServers": {
    "kafka-carrefour": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "-e",
        "KAFKA_BOOTSTRAP_SERVERS=bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431",
        "kafka-mcp-server:2.0.0"
      ]
    }
  }
}

在Windows上配置WSL(Windows Subsystem for Linux)

{
  "mcpServers": {
    "kafka-carrefour": {
      "command": "wsl",
      "args": [
        "--",
        "docker",
        "run",
        "-i",
        "--rm",
        "--network=host",
        "-e",
        "KAFKA_BOOTSTRAP_SERVERS=bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431",
        "kafka-mcp-server:2.0.0"
      ]
    }
  }
}

3. 重启Claude Desktop

# Sur Linux
killall claude
claude &

# Sur Mac
killall Claude
open -a Claude

# Sur Windows - relancer l'application manuellement

4. 检查连接

在Claude中,询问:

Quels sont les outils Kafka disponibles ?

您应该会看到列出的8个MCP工具。

🛠️ 可用的MCP工具

主题/话题

1. kafka_list_topics(Kafka列出主题)

列出集群中的所有主题。

参数 没有

示例 克劳德 :

Liste-moi tous les topics Kafka

回答 :

{
  "topics": ["000", "002", "010", "transactions"],
  "count": 4
}

2. Kafka描述主题(或:Kafka主题描述)

描述一个具有分区、副本和配置的主题。

参数 :

  • topic (字符串,必需):主题名称

示例 克劳德 :

Décris-moi le topic '000' en détail

回答 :

{
  "name": "000",
  "partitions": [
    {
      "partition": 0,
      "leader": 1,
      "replicas": [1, 2, 3],
      "isr": [1, 2, 3]
    }
  ],
  "partitionCount": 3,
  "isInternal": false,
  "configurations": {
    "retention.ms": "604800000",
    "segment.bytes": "1073741824"
  }
}

3. 创建Kafka主题

创建一个新主题。

参数 :

  • topic (字符串,必需):主题名称
  • partitions (数字,可选):分区数量(默认:1)
  • replicationFactor (数字,可选):复制因子(默认:1)

示例 克劳德 :

Crée un topic 'test-events' avec 3 partitions et un facteur de réplication de 2

回答 :

{
  "topic": "test-events",
  "created": true,
  "partitions": 3,
  "replicationFactor": 2,
  "message": "Topic created successfully"
}

4. 删除Kafka主题

删除一个现有主题。

参数 :

  • topic (字符串,必填):主题名称

示例 克劳德 :

Supprime le topic 'old-logs'

信息

5. Kafka消费消息

从主题中消费消息。

参数 :

  • topic (字符串,必需):主题名称
  • maxMessages (数字,可选):最大消息数(默认:10)
  • timeout (数字,可选):毫秒超时时间(默认:5000)

示例 克劳德 :

Consomme 20 messages du topic 'transactions'

回答 :

{
  "topic": "transactions",
  "messages": [
    {
      "topic": "transactions",
      "partition": 0,
      "offset": 1234,
      "key": "user-123",
      "value": "{\"amount\": 99.99}",
      "timestamp": 1698765432000
    }
  ],
  "count": 20
}

6. Kafka消息生产

向主题发布一条消息。

参数 :

  • topic (字符串,必需):主题名称
  • key (字符串,可选):消息密钥
  • value (字符串,必需):消息的值

示例 克劳德 :

Envoie un message de test avec la clé 'test-1' et la valeur '{"status":"ok"}' vers le topic 'events'

回答 :

{
  "topic": "events",
  "partition": 2,
  "offset": 5678,
  "timestamp": 1698765432000,
  "success": true,
  "message": "Message produced successfully"
}

消费者团体

7. kafka_list_consumer_groups(Kafka 列出消费者组)

列出所有消费者群体。

参数 :没有

示例 克劳德 :

Quels sont les consumer groups actifs ?

回答 :

{
  "groups": ["app-consumer", "analytics-group"],
  "count": 2
}

8. Kafka描述消费者组

描述一个消费者组及其成员。

参数 :

  • group (字符串,必填):消费者组的名称

示例 克劳德 :

Décris le consumer group 'app-consumer'

回答 :

{
  "groupId": "app-consumer",
  "state": "Stable",
  "members": [
    {
      "memberId": "consumer-1-abc123",
      "clientId": "consumer-1",
      "host": "/192.168.1.10",
      "assignment": ["events-0", "events-1"]
    }
  ],
  "memberCount": 1,
  "coordinator": 1
}

🧪 测试与调试

使用JSON-RPC进行手动测试

# Test d'initialisation
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}' | \
docker run -i --rm \
  -e KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
  kafka-mcp-server:2.0.0

# Test de listing des tools
echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' | \
docker run -i --rm \
  -e KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
  kafka-mcp-server:2.0.0

# Test d'appel d'un tool
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"kafka_list_topics","arguments":{}},"id":3}' | \
docker run -i --rm \
  -e KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
  kafka-mcp-server:2.0.0

详细日志

# Capture des logs dans un fichier
docker run -i --rm \
  -e KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
  kafka-mcp-server:2.0.0 2>&1 | tee mcp-server.log

# Les logs incluent :
# - Connexion au cluster Kafka
# - Découverte des tools MCP
# - Exécution des commandes
# - Erreurs détaillées

单元测试

# Exécution des tests
mvn test

# Tests avec couverture
mvn test jacoco:report

Kafka 连接性验证

# Test avec kafka-broker-api-versions
docker run --rm confluentinc/cp-kafka:latest \
  kafka-broker-api-versions \
  --bootstrap-server bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431

# Test avec kafka-topics
docker run --rm confluentinc/cp-kafka:latest \
  kafka-topics --list \
  --bootstrap-server bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431

🔐 安全

配置 SASL/PLAIN

docker run -i --rm \
  -e KAFKA_BOOTSTRAP_SERVERS=broker:9093 \
  -e KAFKA_SECURITY_PROTOCOL=SASL_SSL \
  -e KAFKA_SASL_MECHANISM=PLAIN \
  -e KAFKA_SASL_JAAS_CONFIG='org.apache.kafka.common.security.plain.PlainLoginModule required username="admin" password="secret";' \
  kafka-mcp-server:2.0.0

SASL/SCRAM 配置

docker run -i --rm \
  -e KAFKA_BOOTSTRAP_SERVERS=broker:9093 \
  -e KAFKA_SECURITY_PROTOCOL=SASL_SSL \
  -e KAFKA_SASL_MECHANISM=SCRAM-SHA-512 \
  -e KAFKA_SASL_JAAS_CONFIG='org.apache.kafka.common.security.scram.ScramLoginModule required username="admin" password="secret";' \
  kafka-mcp-server:2.0.0

带有SSL证书(卷安装)

docker run -i --rm \
  -v /path/to/certs:/certs:ro \
  -e KAFKA_BOOTSTRAP_SERVERS=broker:9093 \
  -e KAFKA_SECURITY_PROTOCOL=SSL \
  -e KAFKA_SSL_TRUSTSTORE_LOCATION=/certs/truststore.jks \
  -e KAFKA_SSL_TRUSTSTORE_PASSWORD=trustpass \
  -e KAFKA_SSL_KEYSTORE_LOCATION=/certs/keystore.jks \
  -e KAFKA_SSL_KEYSTORE_PASSWORD=keypass \
  kafka-mcp-server:2.0.0

🐳 Docker Compose(中文可译为“Docker 组合”或保持原名,因其为专有名词,直接使用“Docker Compose”更为常见)

创建 docker-compose.yml 为了简化部署:

version: '3.8'

services:
  kafka-mcp-server:
    build: .
    image: kafka-mcp-server:2.0.0
    stdin_open: true
    tty: true
    environment:
      - KAFKA_BOOTSTRAP_SERVERS=bootstrap.dev.kafkahub.external.messaging.vpodg1np.carrefour.com:9431
      - KAFKA_SECURITY_PROTOCOL=PLAINTEXT
    networks:
      - kafka-network

networks:
  kafka-network:
    driver: bridge
docker-compose up -d
docker-compose logs -f kafka-mcp-server

📊 监控与可观测性

Spring Boot Actuator 指标

加入到 pom.xml :

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

加入到 application.yml :

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  metrics:
    export:
      prometheus:
        enabled: true

结构化日志

配置 Logbacklogback-spring.xml) :

<configuration>
    <appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
    </appender>
    <root level="INFO">
        <appender-ref ref="JSON"/>
    </root>
</configuration>

🚀 高级用例

1. 集群健康状况监测

Claude, analyse l'état de santé du cluster Kafka :
1. Liste tous les topics
2. Pour chaque topic, vérifie s'il a des partitions offline
3. Liste les consumer groups et leur état
4. Identifie les groupes en erreur

2. 数据迁移

Claude, copie les 1000 derniers messages du topic 'prod-events' vers 'backup-events'

3. 消息分析

Claude, consomme 100 messages du topic 'logs', analyse les erreurs et donne-moi un résumé

4. 创建测试环境

Claude, crée 5 topics de test (test-1 à test-5) avec 3 partitions chacun, puis envoie 10 messages de test dans chacun

🔄 路线图

  • [ ] 支持Kafka Streams
  • [ ] 模式注册表管理(Avro/Protobuf)
  • [ ] 使用Prometheus进行高级监控
  • [ ] 支持Kafka事务
  • [ ] 额外的REST接口
  • [ ] 支持 Kubernetes/Helm 模板

🤝 贡献

# Fork le projet
git checkout -b feature/ma-fonctionnalite
mvn test
git commit -m "Ajout de ma fonctionnalité"
git push origin feature/ma-fonctionnalite
# Créer une Pull Request

📝 许可证

这个项目采用MIT许可证。

🆘 支持

  • GitHub上的问题 对于错误报告和功能请求
  • 文档 此README文件和JavaDoc
  • 日志 启用DEBUG级别以获取更多详细信息

🎓 资源