What is TerraVision MCP?
TerraVision MCP is an optional stdio server bundled with the TerraVision CLI. It gives an AI agent tools to generate AWS, Azure or GCP architecture diagrams, export the underlying resource graph, build an interactive HTML view, and open the rendered output, all derived from a Terraform plan or a hand-written JSON graph, with no cloud credentials of its own.
It is an optional stdio server bundled with the TerraVision CLI. Instead of an agent inventing an architecture diagram from whatever it can infer, the server returns one derived from a real Terraform plan, with conditionals, count, for_each and module expansion already resolved.
The server runs as a local subprocess and listens on no port. It needs no cloud credentials of its own; when a tool is pointed at raw Terraform, Terraform itself authenticates to the cloud provider to produce the plan.
What changes in an agent's diagrams
- diagram_guide reports the graph format rules, node types, pattern library and gallery designs for one provider, so the agent matches TerraVision's own icon and detail conventions before it draws anything.
- render_graph renders a diagram straight from an inline JSON graph and never runs Terraform, so an agent can preview or correct a design in seconds.
- Warnings point at exactly what will not draw as written, such as an unknown resource type, an arrow into a shared service, or a node listed in two boxes.
- generate_diagram always saves the full set together, PNG, SVG, an editable draw.io drawing and the graph itself, so the same data can be reopened and rendered again.
How the setup works
- Install the optional
mcpextra alongside TerraVision, with pipx, uv, pip or Poetry. - Register the server with your client; it speaks stdio and launches as a local subprocess.
- Pass
--output-dirso generated diagrams land in a fixed, writable location. - Point a tool at a Terraform source path, a Git URL, a
.tvg.jsongraph export, or aplanfile/graphfilepair exported from a CI pipeline.
Who TerraVision MCP is for
Best for
- Teams that already generate diagrams with the TerraVision CLI and want the same renderer callable from inside an agent session.
- Agents working from a Terraform plan or a previously exported graph, so the diagram matches what is actually defined in code rather than a guess.
Not for
- Hand-drawing a fresh architecture diagram with no existing Terraform to parse, a job Excalidraw Icons MCP covers with its own live canvas and vendor icons.
- Loading general design rules for charts, mockups or SVG art rather than cloud architecture diagrams, which Generative UI MCP covers with one on-demand tool.
- Turning a finished diff or Terraform plan into a short HTML explainer page with diagrams and tables, a task Visual Explainer already takes on for an agent's regular output.
- Running a separate local desktop design editor beside the canvas instead of rendering from Terraform code, a role Figmaboy MCP fills with its own stdio server.
Requirements and platform
- Needs
terraformortofu,dotandgvprfrom Graphviz, andgiton PATH; a GUI client that does not inherit a shell's PATH is a common source of "not found" errors. - A Docker image bundles Graphviz, Git and Terraform together, so a client can run the server with nothing else installed locally.
- Reads are unrestricted, matching the CLI's own reach; writes are confined to the configured output location, since outfile rejects separators and
...
Connect TerraVision MCP: Terraform Code to Architecture Diagrams to your AI client
pipx install "terravision[mcp]"
claude mcp add terravision -- terravision mcpInstall the MCP extra
The server is an optional extra, so the default TerraVision install is unchanged. With pipx, run
pipx install "terravision[mcp]"for a new install, orpipx inject terravision mcpto add it to an existing one. Plainpip installdoes not work inside a pipx-managed environment.Or use uv
Run
uv tool install "terravision[mcp]", or call it without installing viauvx --from "terravision[mcp]" terravision mcp, the same way the Claude Code, Codex and Gemini CLI plugins and the MCP Registry entry launch it.Register it with your client
The server speaks stdio: your client launches it as a local subprocess and it listens on no port. In Claude Code, run
claude mcp add terravision -- terravision mcp. In Claude Desktop, install the.mcpbextension from the latest release, or add it by hand under Settings, Developer, Edit Config.Set an output location
Pass
--output-dir /path/for/diagramsin the server args so generated output lands in a fixed, writable location instead of wherever the client happened to launch from.Fix PATH problems
The server is a child process and inherits PATH from the client. If a tool reports a program as not found, pin PATH at registration, for example
claude mcp add terravision -e "PATH=$PATH" -- terravision mcp, or restart the client after PATH changes.
Client configuration
{"mcpServers": {"terravision": {"command": "uvx", "args": ["--from", "terravision[mcp]", "terravision", "mcp", "--output-dir", "/path/for/diagrams"]}}}Endpoints and ports
--output-dir <dir>Where generated output is written; defaults to where the server was startedstdioLocal subprocess launched by the client; listens on no portpatrickchugh/terravisionBundles Graphviz, Git and Terraform; mount a location and pass its container path as the output setting and sourceWhat you can do with it
- Diagrams derived from TerraformGenerated diagrams come from a real Terraform plan, with conditionals, count, for_each and module expansion already resolved, not a guess.
- Provider guide before drawingdiagram_guide gives Graph Format rules, node types, a pattern library and gallery designs for AWS, Azure or GCP so a diagram matches TerraVision's own conventions.
- Graph-only renderingrender_graph draws from an inline JSON graph and never runs Terraform, useful for quick previews or corrections.
- Warnings on what will not drawAn unknown resource type, an arrow into a shared service, or a node listed in two boxes is reported alongside the diagram that still gets drawn.
- Full export setgenerate_diagram always saves PNG, SVG, an editable draw.io drawing and the graph as .tvg.json together.
- Interactive HTML viewgenerate_interactive_html produces an offline, clickable, searchable page with resource metadata embedded.
- No credentials required with a planfilePassing planfile and graphfile from a CI pipeline's own terraform plan skips live Terraform execution and needs no cloud credentials.
- Docker image includedThe published Docker image bundles Graphviz, Git and Terraform, so a client can run the server with nothing else installed.
Tools it exposes
diagram_guide
Returns the graph format rules, node types, pattern library and gallery designs for one provider, for an agent to call before drawing.
render_graph
Renders a diagram from an inline JSON graph without running Terraform, and lists warnings for anything that will not draw as written.
generate_architecture_graph
Returns the architecture as structured graph data, equivalent to terravision graphdata.
generate_diagram
Renders the requested format plus PNG, SVG, an editable draw.io drawing and the graph itself, equivalent to terravision draw.
generate_interactive_html
Produces a self-contained HTML page with clickable, searchable nodes, equivalent to terravision visualise.
open_diagram_file
Opens an output this server rendered in the user's default app, or reveals its location instead.
diagram_file
Returns a rendered output's contents to the diagram view; marked app-only and refuses anything the server did not render.
Frequently asked questions
What is TerraVision MCP?
It is an optional stdio server bundled with the TerraVision CLI. It gives an AI agent tools to turn Terraform code or a JSON graph into AWS, Azure or GCP architecture diagrams, export the underlying resource graph, and build an interactive HTML view, all using the same renderer as the terravision command line tool.
How do I install TerraVision MCP?
With pipx, run pipx install "terravision[mcp]" for a new install or pipx inject terravision mcp to add it to an existing one. uv users can run uv tool install "terravision[mcp]" or call it without installing via uvx --from "terravision[mcp]" terravision mcp. A Poetry install uses poetry install --with test --extras mcp.
Which tools does it expose?
diagram_guide for per-provider rules and examples, render_graph for drawing an inline JSON graph without Terraform, generate_architecture_graph and generate_diagram for Terraform-derived output, generate_interactive_html for an offline HTML view, and open_diagram_file plus diagram_file for retrieving the rendered output afterward.
Does it need my cloud credentials?
No, not on its own. When a tool points at raw Terraform, Terraform itself authenticates to the cloud provider to produce a plan. Passing planfile and graphfile exported from a CI pipeline's own terraform plan skips that step entirely, so no credentials pass through the server at all.
Which clients can use it?
Any client that speaks MCP over stdio, including Claude Code, Claude Desktop, Cursor, Codex CLI, GitHub Copilot in VS Code and Zed. Configuration only differs in where it lives and its key name; all of them need the same command, args and a PATH that includes Graphviz and Terraform.
What happens if part of a graph cannot be drawn as written?
The diagram still renders, and the result lists warnings underneath it, for example an unknown resource type with the closest supported types suggested, an arrow into a shared service, or a node listed in two boxes at once. The same checks back the command-line validator, so the advice matches either way.
Can AI-based diagram refinement run through the MCP server?
No. That refinement step, exposed in the CLI as --ai-annotate, calls out to AWS Bedrock or a local Ollama server. It is left out of the MCP server by design, since a server already being driven by a model does not also need to manage its own model credentials.