{
  "markdown": "# mcp-kafka\n\n[![CI](https://github.com/dockndevai/mcp-kafka/actions/workflows/ci.yml/badge.svg)](https://github.com/dockndevai/mcp-kafka/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![npm](https://img.shields.io/npm/v/@dockndevai/mcp-kafka)](https://www.npmjs.com/package/@dockndevai/mcp-kafka)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) 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.\n\nSafe 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.\n\n## Features\n\n- **Monitoring** — cluster/broker info, topic metadata and offsets, consumer groups, and **per-partition + total consumer lag**.\n- **Management** — create topics, add partitions, alter topic configs, reset group offsets; delete topics/groups (admin).\n- **Access modes** — `read-only` → `read-write` → `admin`, layered so a mode never exposes tools above its level.\n- **Security flags** — topic allowlist, protected/internal topics, delete gating, dry-run, and JSON audit logging (see below).\n- **Auth** — plaintext, TLS, and SASL (PLAIN / SCRAM-SHA-256 / SCRAM-SHA-512).\n\n## Security model\n\n| Concern | Flag | Default | Effect |\n| --- | --- | --- | --- |\n| 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**. |\n| Which topics are in scope? | `KAFKA_TOPIC_ALLOWLIST` | *(all)* | When set, operations on other topics are refused. |\n| Protect internal topics | `KAFKA_PROTECT_INTERNAL_TOPICS` | `true` | Topics starting with `_` can be read but never mutated. |\n| Protect specific topics | `KAFKA_PROTECTED_TOPICS` | *(none)* | Additional read-only-forever topics. |\n| Can it delete? | `KAFKA_ALLOW_DELETE` | `false` | `delete_topic` / `delete_consumer_group` need this **and** admin mode. |\n| Preview without touching the cluster | `KAFKA_DRY_RUN` | `false` | Write/admin tools validate + log intent, then return. |\n| Audit trail | `KAFKA_AUDIT_LOG` | `true` | Emits a JSON line to stderr per guarded operation. |\n\n## Tools\n\n**Read** (`read-only`+): `cluster_info`, `list_topics`, `describe_topic`, `topic_offsets`, `list_consumer_groups`, `describe_consumer_group` (with lag)\n\n**Write** (`read-write`+): `create_topic`, `create_partitions`, `alter_topic_config`, `reset_consumer_group_offsets`\n\n**Admin** (`admin`): `delete_topic`, `delete_consumer_group` (both need `KAFKA_ALLOW_DELETE`)\n\n## Quickstart — add to your agent\n\nPublished on npm as [`@dockndevai/mcp-kafka`](https://www.npmjs.com/package/@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`](.env.example) for every variable and [docs/CLIENTS.md](docs/CLIENTS.md) for the full per-client guide.\n\n**Claude Code** (CLI)\n\n```bash\nclaude mcp add kafka -e KAFKA_BROKERS=\"localhost:9092\" -e KAFKA_MODE=\"read-only\" -- npx -y @dockndevai/mcp-kafka\n```\n\n**Claude Desktop · Cursor · Windsurf** — same block in `claude_desktop_config.json`, `.cursor/mcp.json`, or `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"kafka\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@dockndevai/mcp-kafka\"\n      ],\n      \"env\": {\n        \"KAFKA_BROKERS\": \"localhost:9092\",\n        \"KAFKA_MODE\": \"read-only\"\n      }\n    }\n  }\n}\n```\n\n**OpenAI Codex CLI** — in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.kafka]\ncommand = \"npx\"\nargs = [\"-y\", \"@dockndevai/mcp-kafka\"]\nenv = { KAFKA_BROKERS = \"localhost:9092\", KAFKA_MODE = \"read-only\" }\n```\n\n**VS Code (GitHub Copilot, Agent mode)** — in `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"kafka\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@dockndevai/mcp-kafka\"\n      ],\n      \"env\": {\n        \"KAFKA_BROKERS\": \"localhost:9092\",\n        \"KAFKA_MODE\": \"read-only\"\n      }\n    }\n  }\n}\n```\n\n## Example prompts\n\n- *\"Which consumer groups have the most lag right now?\"*\n- *\"Describe the `orders` topic and show its offsets.\"*\n- *\"Create a topic `events` with 6 partitions and 7-day retention.\"* (needs `read-write`)\n\n## Run from source (development)\n\nPrefer the published package above. To run from a clone:\n\n```bash\nnpm install\nnpm run build\nnode dist/index.js   # with the environment variables set\n```\n\n## Develop\n\n```bash\nnpm run dev\nnpm test\nnpm run typecheck\n```\n\n## Publishing\n\nThis server ships a [`server.json`](server.json) for the official MCP registry and an [`mcpName`](package.json) for npm ownership validation. See **[PUBLISHING.md](PUBLISHING.md)** for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.\n\n## License\n\nMIT\n",
  "bytes": 5048,
  "sha": "bd8b311347147999e675808fe3bc06832678b54575602168115350cf4c089331",
  "repo_slug": "dockndevai/mcp-kafka",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dockndevai_mcp_kafka_2c007d8e/readme"
}