mcp-kafka
This MCP server lets you monitor and manage Apache Kafka clusters, with read-only, read-write, and admin modes controlled by flags.
Monitor Kafka clusters: view cluster info, brokers, controller, and cluster id.
Inspect topics: list topics (optionally including internal ones), describe partitions/replicas/configs, and view earliest/latest offsets.
Track consumer groups: list consumer groups and describe group state with per-partition and total consumer lag.
Manage topics and groups (read-write mode): create topics, add partitions, alter topic configs, and reset consumer group offsets.
Delete resources (admin mode + delete flag): delete topics and consumer groups.
Stay safe by default: starts read-only, supports topic allowlists, protects internal/critical topics, dry-run mode, and audit logging.
Provides monitoring and management for Apache Kafka clusters, including cluster/topic metadata, consumer groups and lag, topic creation and configuration, partition management, offset resets, and guarded deletion of topics and consumer groups.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-kafkaWhich consumer groups have the most lag right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-kafka
A Model Context Protocol server for Apache Kafka. It lets an MCP-capable client (Claude Desktop, Claude Code, etc.) monitor and manage Kafka clusters — topics, partitions, configs, and consumer groups (including lag) — with behaviour controlled entirely by flags.
Safe by default: it starts read-only, can be scoped to an allowlist of topics, protects internal/critical topics from mutation, and gates destructive operations behind an explicit opt-in.
Features
Monitoring — cluster/broker info, topic metadata and offsets, consumer groups, and per-partition + total consumer lag.
Management — create topics, add partitions, alter topic configs, reset group offsets; delete topics/groups (admin).
Access modes —
read-only→read-write→admin, layered so a mode never exposes tools above its level.Security flags — topic allowlist, protected/internal topics, delete gating, dry-run, and JSON audit logging (see below).
Auth — plaintext, TLS, and SASL (PLAIN / SCRAM-SHA-256 / SCRAM-SHA-512).
Related MCP server: Kafka MCP Server
Security model
Concern | Flag | Default | Effect |
What can the server do? |
|
|
|
Which topics are in scope? |
| (all) | When set, operations on other topics are refused. |
Protect internal topics |
|
| Topics starting with |
Protect specific topics |
| (none) | Additional read-only-forever topics. |
Can it delete? |
|
|
|
Preview without touching the cluster |
|
| Write/admin tools validate + log intent, then return. |
Audit trail |
|
| Emits a JSON line to stderr per guarded operation. |
Interactive confirmation | (automatic) | — | Destructive & high-impact actions prompt the human to approve via MCP elicitation before running; clients without elicitation fall back to the |
Tools
Read (read-only+): cluster_info, list_topics, describe_topic, topic_offsets, list_consumer_groups, describe_consumer_group (with lag)
Write (read-write+): create_topic, create_partitions, alter_topic_config, reset_consumer_group_offsets
Admin (admin): delete_topic, delete_consumer_group (both need KAFKA_ALLOW_DELETE)
Quickstart — add to your agent
Published on npm as @dockndevai/mcp-kafka. No clone or build needed — your MCP client runs it on demand with npx. Start in read-only mode; see .env.example for every variable and docs/CLIENTS.md for the full per-client guide.
Claude Code (CLI)
claude mcp add kafka -e KAFKA_BROKERS="localhost:9092" -e KAFKA_MODE="read-only" -- npx -y @dockndevai/mcp-kafkaClaude Desktop · Cursor · Windsurf — same block in claude_desktop_config.json, .cursor/mcp.json, or ~/.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 — in ~/.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 mode) — in .vscode/mcp.json:
{
"servers": {
"kafka": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@dockndevai/mcp-kafka"
],
"env": {
"KAFKA_BROKERS": "localhost:9092",
"KAFKA_MODE": "read-only"
}
}
}
}Example prompts
"Which consumer groups have the most lag right now?"
"Describe the
orderstopic and show its offsets.""Create a topic
eventswith 6 partitions and 7-day retention." (needsread-write)
Run from source (development)
Prefer the published package above. To run from a clone:
npm install
npm run build
node dist/index.js # with the environment variables setDevelop
npm run dev
npm test
npm run typecheckPublishing
This server ships a server.json for the official MCP registry and an mcpName for npm ownership validation. See PUBLISHING.md for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.
License
MIT
Available Tools
6 toolscluster_infoCluster infoARead-onlyIdempotent
Describe the Kafka cluster: brokers, controller, and cluster id.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, open-world, and non-destructive. The description adds value by specifying the output scope (brokers, controller, cluster id), which is especially helpful given there is no output schema. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word earns its place, and the colon-delimited list makes the scope immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool, this is complete: annotations cover the safety profile, and the description states the expected return scope. No output schema exists, but the enumerated components give the agent a clear expectation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the description has no parameter semantics to add. The baseline of 4 for no-parameter tools applies, and the description's component list effectively clarifies what the call returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Describe') and resource ('Kafka cluster'), and enumerates the exact components covered ('brokers, controller, and cluster id'). This clearly distinguishes it from sibling tools focused on topics, consumer groups, and offsets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case by naming the cluster-level resource, but it does not explicitly state when to use this tool over siblings or mention alternatives for topic/group operations. Guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
describe_consumer_groupDescribe consumer group (with lag)BRead-onlyIdempotent
Describe a consumer group's state and compute per-partition and total lag across its topics.
| Name | Required | Description | Default |
|---|---|---|---|
| groupId | Yes | Consumer group id |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that lag is computed across topics, implying a heavier read, but says nothing about cost, latency, or what happens for a group with no active members – a 3 is appropriate given the structured data does most of the work.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence, front-loaded with the primary action and followed by the secondary computation. Nothing wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with full annotation coverage and no output schema, the description is adequate but leaves two gaps an agent would care about: no routing guidance versus list_consumer_groups, and no indication of what the response contains now that the lag computation is the distinguishing feature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with a single groupId parameter documented in the schema, so the schema carries the meaning. The description adds no format or scoping detail (e.g. whether groupId is cluster-qualified), so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (describe) and resource (consumer group), plus a second capability (compute per-partition and total lag). It is clearly distinct from list_consumer_groups by being single-group and lag-aware, though it never names that sibling to make the distinction explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no alternatives named. An agent cannot tell from the description whether to reach for this or list_consumer_groups/describe_topic for a given question; the lag mention implies a use case but does not state it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
describe_topicDescribe topicCRead-onlyIdempotent
Partitions, replicas, in-sync replicas, and non-default configs for a topic.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Topic name |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the only behavioral-adjacent context: which fields are returned (partitions, replicas, ISR, non-default configs). It says nothing about error behavior for a nonexistent topic or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short fragment with no wasted words and the key content is front-loaded. However, it is a fragment rather than a sentence, so brevity comes at the cost of under-specification rather than deliberate conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description is the only source of return-value information, and it does list the main categories of data returned. It is still incomplete for a describe-style tool, omitting leader/replication details, config value semantics, and behavior when the topic does not exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter, and schema description coverage is 100% ('Topic name'), so the schema fully documents it. The description adds no extra meaning about the topic identifier (e.g., naming conventions or whether it must already exist), so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun-phrase fragment that enumerates the payload contents (partitions, replicas, ISR, non-default configs) for a topic, which implies what the tool returns. It never states a verb or explicitly says it retrieves topic metadata, so the purpose is inferred rather than declared. It does at least distinguish itself from siblings like list_topics by being clearly per-topic detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_topics or topic_offsets. An agent must infer from the name and siblings when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_consumer_groupsList consumer groupsARead-onlyIdempotent
List consumer groups and their protocol types.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover safety semantics: read-only, non-destructive, idempotent, and open-world. The description adds that protocol types are included in the result, but gives no additional behavioral context such as pagination, ordering, or whether all known consumer groups are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys both the operation and a useful piece of return data. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list operation, the description plus annotations are sufficient for an agent to select and invoke it correctly. No output schema exists, but none is needed to know how to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is empty with perfect coverage. There is nothing for the description to add about parameter meaning, so the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List') and resource ('consumer groups'), and names the return content ('protocol types'). It can be distinguished from siblings such as describe_consumer_group and list_topics because 'list' plus the resource clearly signals an overview operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus describe_consumer_group for more detail, or when list_topics is more appropriate. The agent must infer the use case from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_topicsList topicsBRead-onlyIdempotent
List topic names. Topics outside the allowlist are filtered out.
| Name | Required | Description | Default |
|---|---|---|---|
| includeInternal | No | Include internal topics (starting with _) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the meaningful behavioral note that topics outside the allowlist are filtered out, but does not explain what the allowlist is or how results are ordered/limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, both front-loaded with the essential facts, with zero filler. The filtering caveat follows immediately after the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-optional-param read tool with no output schema and full annotation coverage, this is mostly adequate. However, the allowlist constraint is stated without any indication of what governs it, and the internal-topic option is left entirely to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter (includeInternal) is fully documented in the schema at 100% coverage, so the schema does the heavy lifting. The description adds no parameter-level detail, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('List topic names'), which clearly distinguishes it from describe_topic, topic_offsets, and list_consumer_groups. The resource (topics) is unambiguous, though it does not explicitly name a sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs describe_topic (which presumably returns details for a single topic) or the other listing tools. Usage is only implied by the word 'list'; no alternatives or conditions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
topic_offsetsTopic offsetsARead-onlyIdempotent
Earliest and latest offsets per partition for a topic (message backlog view).
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Topic name |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description's contribution is naming the returned data (earliest/latest offsets per partition), which does add context annotations lack, but it says nothing about auth requirements, error cases, or whether offsets are live or cached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the resource and the framing use case front-loaded. No wasted words, no repetition of the title beyond what is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must convey return content, and it does name the key fields (earliest and latest offsets per partition). For a simple one-param read tool this is nearly sufficient, though it could state the response shape or ordering more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With a single parameter at 100% schema description coverage, the schema already documents 'topic' as the topic name. The description adds only that offsets are scoped 'per partition', which clarifies granularity but not parameter meaning itself. Baseline 3 applies since schema carries the semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (earliest and latest offsets per partition for a topic) with a clear output-oriented purpose and a parenthetical framing as a backlog view. It is distinguishable from sibling describe_topic by its focus on offsets rather than topic metadata, though it never names an alternative outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase '(message backlog view)' implies the intended use case: gauging consumption backlog. However, it gives no explicit when-to-use/when-not-to-use guidance and does not reference siblings like describe_topic or describe_consumer_group, leaving the agent to infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.2.2- Changed
describe_consumer_group1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
- Changed
describe_topic1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
- Changed
list_topics1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
- Changed
topic_offsets1 field changed- removed
Input schema / additionalPropertiesRemoved value: -false
6 tool updates
v0.1.0- First observed
cluster_info - First observed
describe_consumer_group - First observed
describe_topic - First observed
list_consumer_groups - First observed
list_topics - First observed
topic_offsets
TDQS
Scored across 6 tools
Each tool targets a distinct resource+action: topic listing vs. topic detail vs. offset backlog, consumer group listing vs. group detail/lag, and cluster summary. The list_* vs describe_* split is crisp, and topic_offsets is clearly separated from describe_topic. No two tools could be reasonably confused.
Most tools follow a verb_noun pattern (list_topics, describe_topic, describe_consumer_group, list_consumer_groups), but topic_offsets and cluster_info use noun-phrase forms. The deviation is minor and still readable, and the overall style is snake_case and predictable.
Six tools is well-scoped for a read-only Kafka inspection server, covering the three core surfaces (topics, consumer groups, cluster) without redundancy. Each tool earns its place with no filler.
The read-only inspection surface is coherent and covers topic metadata, offset backlog, consumer group lag, and cluster state with no dead ends within its scope. Gaps exist for write/admin operations (create/delete topics, config changes) and message preview, but these appear intentionally out of scope.
Maintenance
Related MCP Connectors
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
- GentkeyOAuthcom.gentkey
One MCP URL for all your connectors — scoped writes, enforced constraints, and a full audit trail.
- SkycloakOAuthio.skycloak
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
Authenticated MCP server for ClearPolicy policy and compliance workflows.
Related MCP Servers
AlicenseBqualityAmaintenanceAn MCP server implementation built to interact with Confluent Kafka and Confluent Cloud REST APIs.24522 npm168MIT- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables interaction with Kafka clusters to manage topics, monitor consumer groups, and stream messages. It provides a comprehensive suite of tools for broker metadata inspection and local Kafka user management.MIT
- AlicenseBqualityBmaintenanceMCP server for Apache Kafka that allows LLM agents to inspect topics, consumer groups, and safely manage offsets (reset, rewind).1913Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Kafka clusters via MCP, supporting topic management (list, create, delete, inspect), connection initialization, and more through natural language.1Apache 2.0