Kafka MCP Server (mcp-kafka)

Apache Kafka 브로커와 연동하여 LLM이 토픽을 조회하고 실시간 메시지를 확인하거나(Produce/Consume) 프로듀싱할 수 있게 도와주는 Model Context Protocol (MCP) 서버입니다.

기능 (MCP Tools)

• kafka_list_topics: Kafka 브로커 내 생성된 토픽 목록 조회
• kafka_get_topic_metadata: 특정 토픽의 파티션 등 메타데이터 조회
• kafka_produce_message: 특정 토픽에 단일 메시지 전송 (Produce)
• kafka_consume_messages: 특정 토픽의 실시간 메시지를 약 3초간 수신 대기하여 최대 N개까지 조회 (Tail)
• kafka_list_groups: 브로커 내의 컨슈머 그룹 목록 조회 (트러블슈팅)
• kafka_get_group_lag: 특정 컨슈머 그룹과 토픽의 파티션별 Lag 계산 (트러블슈팅)
• kafka_describe_configs: 토픽 또는 브로커의 상세 설정 조회 (ConfigResourceTypes: Topic=2, Broker=4)
• kafka_alter_configs: 토픽 또는 브로커의 설정을 런타임에 동적으로 변경

참고: 모든 도구와 파라미터 설명은 **한국어(KR)와 영어(EN)**가 병기되어 있습니다.

환경 변수 (Environment Variables)

• KAFKA_BROKERS (필수): Kafka 브로커 주소 목록 (기본값: localhost:9092, 콤마로 다중 브로커 연결)
• KAFKA_CLIENT_ID (선택): 식별용 클라이언트 ID (기본값: mcp-kafka-client)
• KAFKA_USERNAME (선택): SASL 인증 사용자 ID (접근 제어가 설정된 클러스터에서 필수)
• KAFKA_PASSWORD (선택): SASL 인증 비밀번호 (접근 제어가 설정된 클러스터에서 필수)
• KAFKA_SASL_MECHANISM (선택): SASL 인증 메커니즘 (기본값: plain)
• KAFKA_SSL (선택): SSL 활성화 여부 (true 또는 false, 보안 통신이 요구될 때 필수)
• PORT (선택): HTTP/SSE 서버 포트 (기본값: 3000)
• TRANSPORT (선택): http 또는 sse 설정 시 HTTP 구동 (미설정 시 stdio)

실행 방법

로컬에서 npx를 사용하여 간편하게 실행할 수 있습니다. 단일 노드(Standalone)와 클러스터(Cluster) 모드를 모두 지원합니다.

1. 단일 노드 (Standalone) 모드

브로커 주소를 1개만 지정합니다.

{
  "mcpServers": {
    "kafka-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-kafka"],
      "env": {
        "KAFKA_BROKERS": "localhost:9092",
        "KAFKA_CLIENT_ID": "mcp-kafka-client",
        "KAFKA_USERNAME": "your_username",
        "KAFKA_PASSWORD": "your_password",
        "KAFKA_SASL_MECHANISM": "plain"
      }
    }
  }
}

2. 클러스터 (Cluster) 모드

여러 브로커 주소를 콤마(,)로 구분하여 지정하면 자동으로 클러스터 토폴로지를 식별하여 연동됩니다.

{
  "mcpServers": {
    "kafka-mcp-cluster": {
      "command": "npx",
      "args": ["-y", "mcp-kafka"],
      "env": {
        "KAFKA_BROKERS": "host1:9092,host2:9092,host3:9092",
        "KAFKA_CLIENT_ID": "mcp-kafka-cluster-client",
        "KAFKA_USERNAME": "your_username",
        "KAFKA_PASSWORD": "your_password",
        "KAFKA_SASL_MECHANISM": "plain"
      }
    }
  }
}

Docker 실행 (HTTP / SSE)

cp .env.example .env
docker-compose up -d --build

이후 http://localhost:3000/mcp 엔드포인트를 통해 접근할 수 있습니다.