Monedula

monedula-sim-link v0.11.0, Apache-2.0

Open your Kafka cluster in the simulator

To visualize a real Kafka cluster, monedula-sim-link takes one snapshot of it and prints a link that opens the Kafka Simulator shaped like the cluster: brokers, topics, partition placement, failures, a sample of data volume, consumer groups and topic configs. Share the link, or let an AI agent build it over MCP.

go install 
go install github.com/monedula-dev/monedula-sim-link/cmd/monedula-sim-link@latest
GitHub Release 
VERSION=0.11.0
curl -L -o monedula-sim-link.tar.gz \
  https://github.com/monedula-dev/monedula-sim-link/releases/download/v${VERSION}/monedula-sim-link_${VERSION}_linux_amd64.tar.gz
tar -xzf monedula-sim-link.tar.gz monedula-sim-link
Start the tutorial GitHub
terminal
monedula-sim-link connect --brokers localhost:9092 --topics orders,payments# one snapshot of orders and payments, printed as one linkhttps://monedula.dev/kafka-simulator/playground?scenario=free&actions=…&size=3x6x3x…

The printed link is shortened here.

How it works

  1. 01

    Snapshot connect

    Read the brokers, topics, partitions, consumer groups and topic configs once.

  2. 02

    Map map names

    Brokers become broker-1 to broker-N. Names the simulator cannot carry are renamed, and --dry-run shows the tables.

  3. 03

    Validate validate

    The link must decode to the same actions and fit in 2048 characters (--force relaxes only the length), or no link is printed.

  4. 04

    Print print the URL

    One link on standard output. The same snapshot always gives the same URL.

  5. 05

    Open open the link

    The playground opens a free-play session shaped like your cluster.

10
brokers at most per link
6
topics at most besides the default orders topic
24
partitions at most per topic
4
consumer groups at most
  1. Your Kafka cluster brokers, topics, groups, configs
  2. connect the command line
    cluster_to_url the MCP tool
  3. One pipeline snapshot, map, validate
  4. Playground link a Kafka Simulator free-play session
The CLI and the MCP tool share one pipeline, so both print the same link from the same snapshot.

It never writes to your cluster

connect produces no records, creates or alters no topics or configs, joins no consumer group and commits no offset. The Metadata request is sent with AllowAutoTopicCreation=false, so looking up a topic can never create it. A principal that may describe the cluster, its topics, its consumer groups and its topic configs is enough. Only the opt-in --producers flag needs more: its DescribeProducers request needs READ on the selected topics.

The whole client surface lives in one source file, snapshot/kafka.go, so you can audit the guarantee in one place, and an end-to-end suite against a three-node KRaft cluster, with Apache Kafka and Confluent Platform images, checks that nothing changed.

The read-only guarantee

Eight requests, and one opt-in
ApiVersionsthe client handshake
Metadatabrokers, topics, leaders, replicas, in-sync replicas
ListOffsetsearliest and latest offset of each partition
ListGroupsthe consumer groups
FindCoordinatorthe lookup of the coordinator of each group
DescribeGroupstheir state and members
OffsetFetchthe offsets they committed
DescribeConfigsthe configs of the selected topics
DescribeProducersonly with --producers: the idempotent and transactional producers that wrote lately

What the link shows

The link opens a free-play session of the Kafka Simulator that is shaped like your cluster. It is a reconstruction from one snapshot, so it says what it approximates: exact real offsets, the controller and rack layout are not carried, and the records are synthetic.

What the link shows

Shape
broker count, selected topics, their real partition counts and replication factors
Placement
reassignments, only for partitions that differ from the simulator default
Failures
offline brokers killed, brokers out of an in-sync replica list slowed
Data volume
up to 8 synthetic keyed records per partition by default, each on its partition
Groups
consumer groups with committed offsets, their members, and lag as a group that drains the backlog
Producers
with --producers: up to 4 idempotent or transactional producers that wrote in the last 15 minutes
Configs
cleanup.policy, min.insync.replicas, retention.ms, retention.bytes

It checks the link before printing it

The playground drops malformed entries silently, so a subtly wrong link would open a session that looks right and shows something else.

Self-validation before printing

The two checks
1The action log must round-trip: encode, decode, encode, identical. Never overridable.
2The link must be at most 2048 characters. --force downgrades this check to a warning.

Real clusters

TLS, SCRAM and mTLS

Connect over plaintext, TLS or mutual TLS, with SASL PLAIN, SCRAM-SHA-256 or SCRAM-SHA-512. Pick topics by exact name, by regular expression, or both.

Prefer the MONEDULA_SIM_LINK_PASSWORD environment variable to --password, so the secret stays out of your shell history.

How to connect to a secured cluster

terminal 
export MONEDULA_SIM_LINK_PASSWORD='...'
monedula-sim-link connect \
  --brokers broker1.example.com:9093,broker2.example.com:9093 \
  --tls --ca-cert ./cluster-ca.pem \
  --sasl-mechanism scram-sha-512 --username viewer

Preview what a link contains

--dry-run prints the size parameter, the tables that map real broker, topic and group names to the names the simulator shows, and the decoded action list, before the link.

With no cluster at hand, demo --dry-run runs a built-in fixture through the same pipeline. The output shown is from that fixture.

Preview a link before you share it

terminal 
monedula-sim-link demo --dry-run
size: 4x3x3xpayments~1~2~1~d~~~~
brokers:
  1 -> broker-1
  2 -> broker-2
  3 -> broker-3
  4 -> broker-4
topics:
  orders -> orders
  payments -> payments
actions (19 entries):
  RP:p1@500
  RG:c1@750
  RA:orders:2:broker-3.broker-1.broker-2@1000
  K:broker-4@1250
  SR:broker-2:1@1500
  ...

For AI agents

An MCP server in the same binary

monedula-sim-link mcp serves the Model Context Protocol over stdio, so Claude Code, Claude Desktop or another MCP client can build links. Its four tools are build_playground_url, open_scenario, validate_actions and cluster_to_url, which snapshots a live cluster the same way connect does.

Use the MCP server

.mcp.json 
{
  "mcpServers": {
    "monedula-sim-link": {
      "command": "monedula-sim-link",
      "args": ["mcp"]
    }
  }
}

Install

go install 
go install github.com/monedula-dev/monedula-sim-link/cmd/monedula-sim-link@latest
GitHub Release 
VERSION=0.11.0
curl -L -o monedula-sim-link.tar.gz \
  https://github.com/monedula-dev/monedula-sim-link/releases/download/v${VERSION}/monedula-sim-link_${VERSION}_linux_amd64.tar.gz
tar -xzf monedula-sim-link.tar.gz monedula-sim-link

Release archives for Linux, macOS and Windows on amd64 and arm64, with a checksums file, are on the releases page. Building from source needs Go 1.25 or newer. Next: see your cluster in the simulator.

Questions

What leaves my machine?
connect talks to your cluster and nothing else, then prints a link. Your credentials are used only to open the connection and are not part of the link, the link names brokers broker-1 to broker-N, and the tool never reads the keys or values of your records. What does go into the link is the topology: the broker count, the names of the shown topics, their partition counts, replication factors and selected configs, the consumer group names, member names derived from client IDs, with --producers the producer IDs of up to four recent writers, and any failures. Treat the link as containing those names when you share it, and use --topics to show only the topics you are happy to share. See what the link shows.
My cluster is bigger than the simulator renders. What happens?
connect keeps the most eventful topics and consumer groups and warns which it kept: the topics you list with --topics first, then topics with under-replicated or offline partitions, consumer lag or readers, and the groups with the most lag. Over 10 brokers or 24 partitions per topic it fails and prints no link, unless you pass --clamp to trim them deterministically. See handle large clusters.
Can I use it at work?
Yes. Apache-2.0 allows commercial use, modification and redistribution as long as you keep the license and notices. Apache Kafka is a trademark of the Apache Software Foundation; monedula-sim-link is an independent project that works with Kafka clusters and is not affiliated with, endorsed by or sponsored by the ASF.

Support

Help from the people who build it

We can help you run monedula-sim-link across a large estate, from design to day-to-day operations.

Talk to us

Part of
Monedula Flock

More free tools for Apache Kafka from the same team. About Flock

Go, AGPL-3.0, v1.0.0

monedula-gitops

GitOps for Apache Kafka: topics, access, quotas, schemas, SCRAM users and Confluent RBAC, from a CLI or a Kubernetes operator.

Product page Docs

Go, AGPL-3.0, v0.10.0

monedula-acl-rbac-converter

A CLI that converts Apache Kafka ACLs into Confluent RBAC role bindings through a checksummed plan and verifies effective access before any ACL is deleted.

Product page Docs

Free, runs in your browser

Kafka Simulator

An interactive, deterministic Apache Kafka simulator in the browser: break a cluster, scrub the timeline and read why it reacted.

Product page Docs