Skip to main content
Glama

mcp-kafka

CI License: MIT npm

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?

KAFKA_MODE

read-only

read-only exposes only monitoring; read-write adds management; admin adds deletes. Tools above the mode are never registered.

Which topics are in scope?

KAFKA_TOPIC_ALLOWLIST

(all)

When set, operations on other topics are refused.

Protect internal topics

KAFKA_PROTECT_INTERNAL_TOPICS

true

Topics starting with _ can be read but never mutated.

Protect specific topics

KAFKA_PROTECTED_TOPICS

(none)

Additional read-only-forever topics.

Can it delete?

KAFKA_ALLOW_DELETE

false

delete_topic / delete_consumer_group need this and admin mode.

Preview without touching the cluster

KAFKA_DRY_RUN

false

Write/admin tools validate + log intent, then return.

Audit trail

KAFKA_AUDIT_LOG

true

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 *_ALLOW_* gate.

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-kafka

Claude 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 orders topic and show its offsets."

  • "Create a topic events with 6 partitions and 7-day retention." (needs read-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 set

Develop

npm run dev
npm test
npm run typecheck

Publishing

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 tools
cluster_infoCluster infoA
Read-onlyIdempotent

Describe the Kafka cluster: brokers, controller, and cluster id.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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)B
Read-onlyIdempotent

Describe a consumer group's state and compute per-partition and total lag across its topics.

ParametersJSON Schema
NameRequiredDescriptionDefault
groupIdYesConsumer group id

TDQS

B3.3/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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 topicC
Read-onlyIdempotent

Partitions, replicas, in-sync replicas, and non-default configs for a topic.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYesTopic name

TDQS

C2.8/5.0
Behavior3/5

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.

Conciseness3/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose3/5

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.

Usage Guidelines2/5

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 groupsA
Read-onlyIdempotent

List consumer groups and their protocol types.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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 topicsB
Read-onlyIdempotent

List topic names. Topics outside the allowlist are filtered out.

ParametersJSON Schema
NameRequiredDescriptionDefault
includeInternalNoInclude internal topics (starting with _)

TDQS

B3.3/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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 offsetsA
Read-onlyIdempotent

Earliest and latest offsets per partition for a topic (message backlog view).

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYesTopic name

TDQS

A3.6/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

  1. 4 tool updatesv0.2.2
    • Changeddescribe_consumer_group1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
    • Changeddescribe_topic1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
    • Changedlist_topics1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
    • Changedtopic_offsets1 field changed
      • removedInput schema / additionalProperties
        Removed value: -false
  2. 6 tool updatesv0.1.0
    • First observedcluster_info
    • First observeddescribe_consumer_group
    • First observeddescribe_topic
    • First observedlist_consumer_groups
    • First observedlist_topics
    • First observedtopic_offsets

TDQS

A3.6/5.0

Scored across 6 tools

Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    An 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
  • A
    license
    B
    quality
    B
    maintenance
    MCP server for Apache Kafka that allows LLM agents to inspect topics, consumer groups, and safely manage offsets (reset, rewind).
    19
    13
    Apache 2.0
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Kafka clusters via MCP, supporting topic management (list, create, delete, inspect), connection initialization, and more through natural language.
    1
    Apache 2.0