iso-topology MCP
iso-topology turns an architecture description into an isometric SVG diagram that an agent validates and repairs by contract
- 74 ★ on the repository
- Last commit
- Apache-2.0
Minimal access
Why this level
- Writes SVG, HTML and PNG files to the chosen folder and runs a local preview server on localhost with `isotopo serve`
Install
- Works in
Manual install
claude mcp add isotopo -- isotopo-mcpFirst go install github.com/MarkovWangRR/iso-topology/cmd/isotopo-mcp@latest.
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- Writes SVG, HTML and PNG files to the chosen folder and runs a local preview server on localhost with `isotopo serve`
This is third-party code. Review the repository files before installing.
What it does
iso-topology draws architecture diagrams as code: a YAML description or a D2 graph becomes an isometric 2.5D SVG diagram that can live in Git and be compared in diffs. Element positions come from `layout` and `place` relations, with no pixel coordinates. One static binary runs offline, and the output is byte-deterministic: the same input gives the same SVG. The agent works in a loop. `isotopo capabilities` returns a machine-readable DSL inventory, `isotopo validate` checks the scene and suggests fixes, `isotopo evaluate` scores crossings, overlaps and composition, and `isotopo repair --compose --write` fixes overlaps, contrast and alignment. Then `isotopo render` draws the result, `isotopo snapshot` makes a PNG for visual self-review, and `isotopo preview` shows a single node or edge. The server connects to Claude Code with `claude mcp add isotopo -- isotopo-mcp`. A skill variant exists too: the `scripts/install-skill.sh` script from a clone of the repository. The library holds over 200 icons, including real brand logos.
Who it is for. Engineers and technical writers who need neat infrastructure diagrams in the repository, updated by an agent together with the code.
Good fit when
- You need a dark-style architecture diagram for documentation and want it from a phrase like "draw a real-time ClickHouse analytics architecture"
- The diagram changes whenever the infrastructure changes and is better kept as text beside the code
- The agent should check the diagram for crossings and overlaps itself before showing it to you
- Mermaid and D2 give flat flowcharts and you want an expressive isometric style
Not a fit when
- You need an ordinary flat flowchart: Mermaid or D2 is enough
- You need a sequence diagram or UML: the tool draws architecture diagrams
- A person must edit the diagram by mouse in Figma: here the main path is text and an agent
Example request
Draw an isometric architecture diagram of our LangGraph service in a dark style, check it with validate and evaluate and save the SVG to docs/MCP
- Transport
- stdio
- Authentication
- not required
Limitations
- It installs through Go: `go install` for the `isotopo` and `isotopo-mcp` binaries, and Go must be installed.
- The README install commands point to the module `github.com/MarkovWangRR/iso-topology`, whose owner in the path differs from the repository owner NexusFox88: check the path before running.
- The output is isometric 2.5D, and the tool draws no other kinds of diagrams.
- For Claude Code an MCP server and a skill are described, and other clients have `llms.txt` and a prompt template.
How to disable. Remove the server with claude mcp remove isotopo and delete the isotopo and isotopo-mcp binaries from `$GOPATH/bin`. The skill is removed by deleting its folder under `~/.claude/skills`. Diagrams you created stay as ordinary project files.
FAQ
How do I connect iso-topology to Claude Code?
Install the binary with `go install github.com/MarkovWangRR/iso-topology/cmd/isotopo-mcp@latest` and run `claude mcp add isotopo -- isotopo-mcp`. Instead of MCP you can install the skill with `scripts/install-skill.sh`.
How is iso-topology different from Mermaid?
Mermaid and D2 draw flat flowcharts, while iso-topology produces isometric 2.5D diagrams with gradients, glow and brand logos. The DSL is checked against a contract, so the agent fixes errors itself.
Does rendering need a browser or fonts?
No. A single static binary with no dependencies renders the diagram offline in milliseconds, with no browser or fonts.
Can I start from a plain D2 graph?
Yes. Write `user -> api -> db` to `scene.d2` and run `isotopo render scene.d2 ./out` to get `out/topology.svg`. `isotopo serve scene.d2` opens an editor at localhost:8731.
What do validate and evaluate check?
`isotopo validate` lints the scene against a JSON schema with did-you-mean suggestions, and `isotopo evaluate` scores crossings, overlaps and composition. The output is structured, so the agent fixes the scene without a human.
Discussion
No questions or reviews yet.
Related
MCP serversA diagram canvas that Claude Code and Codex draw on over MCP: Mermaid, D2 and Structurizr in, a repository map, SVG and PDF out
The official draw.io MCP server: an agent builds diagrams from XML or Mermaid and opens them in the draw.io editor
Smart Drawio
Smart Drawio Next
An MCP server and skill for editable draw.io diagrams: an agent generates XML from a prompt, validates references, repairs tags and applies themes
Markdy
markdy-com
Animated diagrams as code: text turns into a step-by-step explanation of architecture. A library, a CLI and an MCP server, HTML output
A skill that draws validated architecture, workflow, sequence and data-flow diagrams as one interactive HTML file
Next AI Draw.io is an MCP server and plugin where the agent draws draw.io diagrams on a live browser canvas that you can edit by hand
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| iso-topology (this card) | no | not required | 74 | |
| Diagram Design | no | 66,822 | a skill set for diagram design with no text DSL that validates and repairs | |
| Architecture Diagram Generator | no | 7,589 | a diagram generator for agents without isometry or a machine contract | |
| Mermaid CLI | no | 5,163 | renders flat Mermaid diagrams and has no isometry |
README in short
The README presents iso-topology as a diagram-as-code tool with isometric output aimed at agents. It shows a YAML example with styles and placement relations, a one-minute quick start by hand and with an agent, then the loop capabilities, validate, evaluate, repair, render, snapshot, preview. Documentation, a gallery, a dependency-free binary and an icon set with brand logos follow.