CLI Reference

KafkaMCP is distributed as a single binary named kafkamcp. This page documents all subcommands and flags.

Global flags

Flag	Short	Default	Description
--config	-c	kafkamcp.yaml	Path to configuration file.
--log-level	—	—	Override log level (debug, info, warn, error). When set, this takes precedence over server.log_level in the config file.
--debug	—	false	Enable debug logging (shorthand for --log-level debug).

Commands

kafkamcp (root)

Start the MCP server using the configuration file.

kafkamcp --config /path/to/kafkamcp.yaml

The server runs in the foreground. Use the server.transport config value to control the transport mode (stdio, sse, or streamable-http).

Override log level at runtime:

kafkamcp --config kafkamcp.yaml --log-level debug

The --log-level flag overrides the server.log_level value in the configuration file without modifying it.

kafkamcp version

Print the version string and exit.

kafkamcp version

Example output:

kafkamcp 0.1.0

kafkamcp validate

Validate the configuration file and exit. Returns a non-zero exit code if validation fails.

kafkamcp validate --config /path/to/kafkamcp.yaml

Example output (success):

Configuration is valid.

Example output (failure):

Error: configuration validation failed: at least one cluster is required

Use this before deploying config changes to catch errors early.

kafkamcp validate-config

Validate a configuration file with detailed output. Unlike validate, this command accepts a positional file argument and prints a summary of the parsed configuration (transport, clusters, policies, masking).

kafkamcp validate-config /path/to/kafkamcp.yaml
kafkamcp validate-config --config /path/to/kafkamcp.yaml

Example output (success):

Configuration /path/to/kafkamcp.yaml is valid.
  Transport: stdio
  Clusters:  1
    [0] local (localhost:9092)
  Policy:    default_deny=false (open access)

Example output (failure):

Error: configuration validation failed: at least one cluster is required

kafkamcp dev

Start KafkaMCP in local read-only development mode. It uses the configured core-read surface and does not create topics or seed data automatically.

kafkamcp dev --config kafkamcp.yaml

For a deterministic lag, DLQ, and schema-drift scenario, run:

make incident-demo-up incident-demo-setup
kafkamcp dev --config examples/incident-demo/kafkamcp-demo.yaml

kafkamcp serve

Start the MCP server. This is an alias for running kafkamcp without a subcommand — the behavior is identical.

kafkamcp serve --config /path/to/kafkamcp.yaml
kafkamcp serve --config kafkamcp.yaml --log-level debug

Use serve when you want an explicit subcommand for clarity in scripts or process managers.

kafkamcp init

Generate a starter configuration file. Writes to stdout by default or to a file with --output.

kafkamcp init
kafkamcp init --transport sse --schema-registry http://localhost:8081
kafkamcp init --output kafkamcp.yaml

Flag	Short	Default	Description
--output	-o	—	Write config to file instead of stdout.
--transport	—	stdio	Transport type (stdio, sse, streamable-http).
--bootstrap-servers	—	localhost:9092	Kafka bootstrap servers.
--schema-registry	—	—	Schema Registry URL (optional).
--claude-desktop	—	false	Output a claude_desktop_config.json snippet for Claude Desktop integration.

How it differs from manual config creation:

kafkamcp init generates a valid, minimal YAML configuration with sensible defaults. It is the fastest way to get started — instead of writing YAML from scratch, run kafkamcp init --output kafkamcp.yaml and customize the result. Use --claude-desktop to also emit the JSON snippet needed to register KafkaMCP with Claude Desktop.

Exit codes

KafkaMCP uses standard exit codes for scripting and CI/CD integration.

Code	Meaning	Example cause
0	Success	Server shut down cleanly, config validated, version printed.
1	General/configuration error	Invalid flags, config error, or startup failure.

In CI/CD pipelines you can rely on the exit code to gate deployments:

kafkamcp validate --config kafkamcp.yaml || exit 1

Command errors are printed to stderr; runtime logs use the configured structured logger.

Examples

Start with stdio transport (Claude Desktop):

kafkamcp --config kafkamcp.yaml

Start with verbose logging for debugging:

kafkamcp --config kafkamcp.yaml --log-level debug

Validate config in CI/CD pipeline:

kafkamcp validate --config kafkamcp.yaml && echo "Config OK"

Check installed version:

kafkamcp version

Environment variables

KafkaMCP recognizes the following environment variables at runtime:

Variable	Default	Description
KAFKAMCP_TRANSPORT	—	Overrides server.transport from the config file. Valid values: stdio, sse, streamable-http.
KAFKAMCP_LOG_LEVEL	—	Overrides server.log_level from the config file. Valid values: debug, info, warn, error. The --log-level CLI flag takes precedence over this variable.
KAFKAMCP_ALLOW_INSECURE	—	Set to true to allow insecure_skip_verify in connect_tls settings. Required as an explicit opt-in for skipping TLS certificate verification. Not recommended for production.

Additionally, KafkaMCP expands ${VAR} and ${VAR:-default} syntax in the YAML config file using process environment variables. See Configuration for details.