denizgursoy/kafka-mcp

An MCP server that exposes Kafka debugging as tools an LLM can call. It speaks
MCP over stdio by default, optionally serves streamable HTTP, and talks to Kafka
with franz-go.
One process can connect to several Kafka clusters. In stdio mode, one endpoint
is selected for the session. In HTTP mode, each endpoint has its own path, so a
session is bound to one cluster by how it connects rather than by a parameter a
caller could forget to send.
## Install
Every release ships the same server four ways:
Binary: kafka-mcp archives on the
releases page.
Put kafka-mcp on your PATH.
MCP Bundle: kafka-mcp .mcpb on the same page,
for macOS on Apple Silicon, Linux (amd64, arm64) and Windows (amd64). Open
it in a client that installs bundles, such as Claude Desktop. It asks for
your configuration file and, when that file has several endpoints, which
one to serve. Intel Macs use the binary or the image.
Container image: ghcr.io/denizgursoy/kafka-mcp: . It starts with
--server; for stdio, mount the file and pass --server=false:
sh
docker run -i --rm \
--mount type=bind,src=$PWD/kafka-mcp.yaml,dst=/config/kafka-mcp.yaml,readonly \
-e CONFIGFILE=/config/kafka-mcp.yaml \
ghcr.io/denizgursoy/kafka-mcp:latest --server=false --endpoint local
MCP Registry: listed as io.github.denizgursoy/kafka-mcp in the
official registry,
with the image and the bundles, so a client that reads the registry can
install it from there.
How releases reach the registry and the other catalogs is in
PUBLISHING.md.
## Configuration
kafka-mcp.{toml,yaml,yml,json} in the working directory, ~/.config/kafka-mcp/ or /etc configures the server. The http block is used only with --server.
yaml
http:
address: ":8090"
basepath: /kafka-mcp # optional; prefixes every endpoint and /healthz
# publicurl: https://kafka.example.com # optional; the address download links use
clusters:
prod:
brokers:
kafka-1:9093
kafka-2:9093
security:
tls:
enabled: true
cafile: /etc/kafka/ca.pem
# certfile: /etc/kafka/client.pem # optional mTLS; requires keyfile
# keyfile: /run/secrets/client.key
sasl:
scram:
enabled: true
algorithm: SCRAM-SHA-256 # or SCRAM-SHA-512
user: kafka-mcp-readonly
pass: "{env:KAFKAPASSWORD}" # or passwordfile: /run/secrets/kafka
preprod:
brokers: kafka-preprod:9093
endpoints:
prod-read:
cluster: prod
path: /mcp
description: Production investigation and debugging
readonly: true
prod-write:
cluster: prod
path: /mcp/rw
description: Approved production changes
tools:
copymessage: false
preprod:
cluster: preprod
path: /mcp/preprod
clusters owns Kafka connection details: brokers, TLS and SASL. endpoints
owns the policy and, in HTTP mode, the MCP route. Stdio selects an endpoint by
name and does not use its path. Several endpoints may reference one cluster, so
the example reuses one production connection at /kafka-mcp/mcp in read-only
mode and /kafka-mcp/mcp/rw in writable mode. Paths are exact: /mcp does not
capture /mcp/rw. description is optional and is reported by serverconfig
so a caller knows what the endpoint is intended for.
http.basepath prefixes endpoint paths and the liveness route. A leading or
trailing slash on an endpoint path is optional. Paths must be unique and may
not be /, /healthz, or contain a query or fragment. When path is omitted,