TerraVision: cloud architecture diagrams from Terraform or a prompt

Two directions through one local Python package

TerraVision is a Python package that draws cloud architecture pictures in the official AWS, Azure and Google Cloud icon sets, and it works from either end of the infrastructure lifecycle. The project description names three routes: AI prompt or JSON to diagram, diagram to Terraform through an MCP server, and Terraform to diagram through the CLI or a CI/CD job. Nothing runs against a cloud account, so the tool sits on the desk of a platform engineer who needs a picture of a stack and, in the other direction, needs Terraform back from one. pyproject.toml sets requires-python to >=3.11 and builds through poetry-core>=1.0.0, and one console script named terravision is wired to terravision.terravision:main. Ask for a design in words and the assistant returns a drawing; hand over the Terraform and the same package returns the drawing instead. The last push landed on 2026-10-05 and the repository is not archived, and the version recorded in pyproject.toml is 0.52.0.

Where the MCP server meets Claude Desktop and ChatGPT

The documented install path treats an AI assistant as the front end. TerraVision installs as an extension in Claude Desktop and a plugin in the ChatGPT desktop app, where the diagram appears right in the chat, and the same setup is named for Claude Code, Codex CLI, GitHub Copilot, Cursor and any other MCP client. The repository carries a manifest for each of those worlds at the top level: .claude-plugin/, .codex-plugin/, gemini-extension.json and gemini-extension.md, plus server.json and an mcpb/ directory, with llms.txt sitting beside them for agents that read a plain text brief. One Python package backs every host, so switching assistants changes nothing about the drawing. Claude Desktop brings its own copy of uv on Windows and macOS, which is why that install step is flagged as not needed there.

Graphviz and Git are the binaries you cannot skip

Rendering is done by Graphviz and version control by Git, and both are listed as install-once prerequisites, joined by uv for Claude Code, Codex, Antigravity CLI and other MCP clients. Terraform appears in the same list but marked optional, needed only to draw from Terraform code. Linux has a wrinkle worth reading twice. Graphviz moved its Neato layout engine into a separate plugin package in recent distributions, so the Debian and Ubuntu block adds a second command, sudo apt install libgvplugin-neato-layout8, with a comment limiting that step to Ubuntu 26.04 and later, also Debian 14 forky or testing, and telling users on older systems such as Ubuntu 24.04 to skip it because graphviz already includes it. Missing that plugin package on a new distribution is the kind of failure that shows up as an empty layout, not as a clean error.

Installing on macOS, Windows and Debian or Ubuntu

Homebrew covers macOS in three lines, and the third one is the Terraform install you can leave out if you never draw from code:

brew install graphviz git
brew install uv                        # not needed for Claude Desktop
brew install hashicorp/tap/terraform   # optional: to draw from Terraform code

Windows uses winget from PowerShell with the same split between what you need and what you can skip:

winget install --id Graphviz.Graphviz -e
winget install --id Git.Git -e
winget install --id astral-sh.uv -e    # not needed for Claude Desktop
winget install --id Hashicorp.Terraform -e   # optional: to draw from Terraform code

After either block, open a new terminal and restart the AI app, because a running application does not see programs added to your PATH. Debian and Ubuntu start with Graphviz and Git, plus the layout plugin on newer distributions:

sudo apt install graphviz git
sudo apt install libgvplugin-neato-layout8

One gap sits in that Linux block: the curl line for uv stops mid address at https://astral.sh/uv/instal, so the Linux path is not reproducible from the README alone and that step has to be taken from the documentation site.

Icons, grouping and the edge labels Graphviz draws

One promise about the output puts the weight on the repository's asset directories: every resource drawn inside its VPC, subnet, zone or resource group, using official vendor icons instead of generic boxes. Two top level directories, resource_classes/ and resource_images/, are where that per service material lives, and A Graphviz filter program sits beside them under the name shiftLabel.gvpr. .gvpr files are the Graphviz language for rewriting a drawing while it is produced, which is where edge label handling belongs when a picture has to show who calls whom. No coverage count is published anywhere, so the honest test of scope is the gallery: twelve designs, each shipped with the prompt and the source file behind it, with matching inputs kept under examples/graphs/ in the repository.

The MCP extra and the pinned HCL2 parser behind code generation

The direction that turns a picture back into code runs through the Model Context Protocol server, and that server is not in the base install. pyproject.toml puts it in an optional extra, mcp>=2.0,<3, beside pillow>=10, with a comment explaining that Pillow scales the diagram preview returned inline to chat apps and that the extra stays optional so the default install is unchanged for people who only want the CLI. Reading Terraform is a separate concern again, pinned hard in both dependency lists to python-hcl2==4.3.0 with an equality sign rather than a floor, while the repository also carries its own hcl2/ directory at the top level. That exact pin is the piece to watch during an upgrade: nothing lets a newer parser in without an edit.

The container picks its Terraform version at build time

The Dockerfile is where both halves of the project meet in a single image. It starts from alpine:3.23, adds graphviz alongside graphviz-dev, which the comment ties to pygraphviz and graphviz2drawio, then resolves Terraform during the build rather than pinning a number:

TF_VERSION=$(curl -s https://api.github.com/repos/hashicorp/terraform/releases/latest | jq -r '.tag_name' | sed 's/^v//')

Two further lines decide how the package lands in that image:

pip install ".[mcp]"

That install deliberately pulls the optional extra so terravision mcp works inside the container, which a plain install from the project metadata would not provide. The image clones tfenv as a second Terraform version manager, drops to a non root account with uid 1000, and sets /project as the working directory for the code you mount. The practical consequence is that one image tag can carry a different Terraform binary on two different build days.

requirements.txt and pyproject.toml disagree on two dependencies

Two dependency lists ship in the repository and they are not the same list. pyproject.toml asks for graphviz>=0.21 while requirements.txt asks for graphviz>=0.20.1, so the floor you land on depends on which file you install from. More seriously, boto3 sits in pyproject.toml as boto3>=1.35.0 and is absent from requirements.txt, together with the MCP extra and Pillow; an environment assembled from requirements.txt alone has no AWS SDK and no protocol server on the path. Everything else in the two files lines up, including the exact pin on python-hcl2==4.3.0. The container does not use requirements.txt at all, so the thinner list only bites people who install from source by hand or bake it into their own image.

Editorial conclusion

Adopt TerraVision when your AWS, Azure or GCP footprint already lives in Terraform and you need a readable picture of it, and run it wherever Graphviz is installed. It is the wrong choice if you need a canvas to edit, a shared diagram library, or a pixel match with the cloud console. Check three things before you commit: whether resource_classes/ covers the services you actually run, whether boto3 is present when you install from requirements.txt, and which Terraform version your image locked at build time.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. patrickchugh/terravision on GitHub
3. Project website
4. README
5. Releases