kafka-docker-playground MCP server

An MCP server that exposes the live state of a local kafka-docker-playground to an AI coding agent: what is running, which connectors are broken and why, what the container logs actually say, and which of the ~2500 example scripts matches what you are trying to reproduce.

It deliberately does not re-serve the playground CLI's command syntax. An agent working in the repo already has scripts/cli/playground.json, scripts/cli/src/bashly.yml and playground --help; a second, lossy copy of that is worse than none. Everything here needs a running Docker daemon, a Connect REST endpoint or a filesystem scan — things a static reference cannot provide.

Tools

Why these are worth a tool call

On a real 918 KB / 10 645-line connect.log, playground_logs returns 4.5 KB containing the full Caused by: chain — a ~200× reduction with the diagnostic content intact. playground_find_example indexes 2558 scripts in under a second and answers "s3 sink proxy" with connect/connect-aws-s3-sink/s3-sink-proxy.sh. 95% of those scripts are indexed with their connector class; the rest are the client, ksqlDB, Flink and environment examples, which have no connector.

Related MCP server: Kafka MCP Server

Secrets

playground.ini stores Confluent Cloud API keys in cleartext, connector configs carry passwords, and logs leak JAAS strings. Every response passes through a redaction layer that masks secret-looking config keys, JAAS/JDBC inline passwords, key:secret pairs, credentials in URLs and Authorization headers. Shell variable references ($AWS_SECRET_ACCESS_KEY) and ordinary settings (key.converter) are left readable.

All tools are read-only. Nothing here starts, stops, or reconfigures anything.

Installation

Claude Code, from the playground repository

Nothing to install. kafka-docker-playground ships a .mcp.json at its root that declares this server, so running claude from the checkout offers it — accept it once. playground ai accepts it for you.

Any MCP client

{
  "mcpServers": {
    "mcp-playground": {
      "command": "npx",
      "args": ["-y", "github:vdesabou/kafka-docker-playground-mcp-server"]
    }
  }
}

No path is needed when the client starts the server inside the playground checkout: the repo root is found by walking up from the working directory. When it does not — Claude desktop, for instance — add "env": { "PLAYGROUND_REPO_ROOT": "/path/to/kafka-docker-playground" }.

A local clone, for working on the server itself

A local scope server shadows the one from .mcp.json, so point it at your build and the playground repository keeps working unchanged:

npm install && npm run build
claude mcp add mcp-playground -- node /path/to/kafka-docker-playground-mcp-server/dist/index.js

Configuration

The server needs the docker CLI on its PATH and a reachable daemon — it inspects the playground's containers, so it runs on the host rather than in a container of its own.

Development

npm run dev              # run from source with tsx
npm run watch            # reload on change
npm run fastmcp:inspect  # web inspector

src/
├── index.ts      # tool definitions
├── config.ts     # repo root resolution
├── state.ts      # playground.ini + run history
├── docker.ts     # docker CLI wrapper
├── connect.ts    # Connect REST (on-prem + Confluent Cloud) endpoint resolution
├── logs.ts       # error extraction, de-duplication, stack-trace collapsing
├── examples.ts   # example index, search and detail extraction
├── http.ts       # request helper with client-certificate support
├── redact.ts     # secret redaction
└── exec.ts       # shell-free subprocess helper

Related

For modifying the playground CLI (bashly conventions, regeneration, where helpers go), use the playground-cli skill in kafka-docker-playground/.claude/skills/playground-cli/ instead. The two do not overlap: the skill covers authoring the CLI, this server covers observing a running environment.

Built with FastMCP.